@pascal-app/editor 0.7.0 → 0.9.1

package/src/hooks/use-selection.ts

@@ -0,0 +1,64 @@
+'use client'
+
+import type { AnyNode, AnyNodeId } from '@pascal-app/core'
+import { useScene } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+
+/**
+ * Resolved current selection — selected node IDs plus a convenience
+ * lookup into the live scene store. Returned shape is intentionally
+ * narrow: hosts that need richer per-node state can compose this with
+ * `useScene()` themselves.
+ */
+export type Selection = {
+  /** Multi-select node IDs (drives the rest of the editor's UI). */
+  selectedIds: AnyNodeId[]
+  /** Currently active building context — surfaces / palettes filter on this. */
+  buildingId: AnyNodeId | null
+  /** Currently active level context. */
+  levelId: AnyNodeId | null
+  /** Currently active zone context. */
+  zoneId: AnyNodeId | null
+  /**
+   * Resolved nodes for `selectedIds`. Missing entries (deleted nodes) are
+   * filtered out, so the array length may be ≤ `selectedIds.length`.
+   */
+  selectedNodes: AnyNode[]
+  /**
+   * The single selected node, or `null` when zero or multiple nodes are
+   * selected. Useful for "save as preset" / inspector gating where the
+   * UI only makes sense for a unique selection.
+   */
+  selectedNode: AnyNode | null
+}
+
+/**
+ * Subscribe to the current selection. Equivalent to reading from
+ * `useViewer().selection` plus a live `useScene()` lookup, packaged as
+ * a single hook so consumers building their own shells (community,
+ * standalone editor app, embedders) don't have to learn the two
+ * separate stores.
+ *
+ * Selection state intentionally lives in `useViewer` (it tracks the
+ * camera / visibility hierarchy: building → level → zone → nodes), not
+ * `useScene` — see `wiki/architecture/scene-registry.md`.
+ */
+export function useSelection(): Selection {
+  const selection = useViewer((s) => s.selection)
+  const nodes = useScene((s) => s.nodes)
+
+  const selectedIds = selection.selectedIds as AnyNodeId[]
+  const selectedNodes = selectedIds
+    .map((id) => nodes[id])
+    .filter((n): n is AnyNode => n !== undefined)
+  const selectedNode = selectedNodes.length === 1 ? (selectedNodes[0] ?? null) : null
+
+  return {
+    selectedIds,
+    buildingId: (selection.buildingId ?? null) as AnyNodeId | null,
+    levelId: (selection.levelId ?? null) as AnyNodeId | null,
+    zoneId: (selection.zoneId ?? null) as AnyNodeId | null,
+    selectedNodes,
+    selectedNode,
+  }
+}

package/src/index.tsx

@@ -1,13 +1,162 @@
+// Re-exports of the scene / viewer hooks so consumers composing their
+// own shells on top of `@pascal-app/editor` (community-app, embedders)
+// don't have to learn three separate package imports. The canonical
+// definitions still live in `@pascal-app/core` / `@pascal-app/viewer`.
+export { useScene } from '@pascal-app/core'
+export { useViewer } from '@pascal-app/viewer'
 export type { EditorProps } from './components/editor'
 export { default as Editor } from './components/editor'
+// Headless component aliases: the implementation files keep their
+// internal names (`ParametricInspector`, `FloatingActionMenu`) because
+// 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 { FloatingActionMenu as FloatingMenu } from './components/editor/floating-action-menu'
+export { formatMeasurement, MeasurementPill } from './components/editor/measurement-pill'
+export {
+  type SnapshotCameraData,
+  ThumbnailGenerator,
+} from './components/editor/thumbnail-generator'
+// SVG path builders for arc / annular-sector / arrow-head shapes —
+// inlined into `kind: 'path'` / `kind: 'polygon'` primitives by curved
+// stair rendering in `nodes/src/stair/floorplan.ts`.
+export {
+  buildSvgAnnularSectorPath,
+  buildSvgArcPath,
+  buildSvgArrowHeadPoints,
+  getArcPlanPoint,
+} from './components/editor-2d/svg-paths'
+// Phase 5 Stage D transitional exports — pure drafting / angle helpers
+// consumed by kind-owned drag actions in @pascal-app/nodes. Stage F
+// cleanup moves these into @pascal-app/nodes (fence/drafting.ts +
+// shared/segment-angle.ts) once every Stage D port is in.
+export {
+  createFenceOnCurrentLevel,
+  type FencePlanPoint,
+  snapFenceDraftPoint,
+} from './components/tools/fence/fence-drafting'
+// 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.
+export {
+  calculateCursorRotation,
+  calculateItemRotation,
+  getSideFromNormal,
+  isValidWallSideFace,
+  snapToGrid,
+  snapToHalf,
+  snapUpToGridStep,
+  stripTransient,
+} from './components/tools/item/placement-math'
+export type { PlacementState } from './components/tools/item/placement-types'
+// Item placement / move primitives. Re-exported here so the registry-driven
+// item move-tool in `@pascal-app/nodes` can compose them — same hooks the
+// legacy `MoveItemContent` + `ItemTool` use. Once item placement is fully
+// owned by `nodes`, these can be inlined there and dropped from editor.
+export { type DraftNodeHandle, useDraftNode } from './components/tools/item/use-draft-node'
+export {
+  type PlacementCoordinatorConfig,
+  usePlacementCoordinator,
+} from './components/tools/item/use-placement-coordinator'
+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'
+// Phase 5 Stage D — PolygonEditor for slab/ceiling boundary + hole editors.
+export {
+  PolygonEditor,
+  type PolygonEditorProps,
+} from './components/tools/shared/polygon-editor'
+export {
+  formatAngleRadians,
+  getAngleArcToSegmentReference,
+  getAngleToSegmentReference,
+  getSegmentAngleReferenceAtPoint,
+  type SegmentAngleReference,
+} from './components/tools/shared/segment-angle'
+// Stair placement defaults — used by the kind-owned stair / stair-segment
+// panels. Re-exported from `components/tools/stair/stair-defaults.ts`.
+export {
+  DEFAULT_CURVED_STAIR_INNER_RADIUS,
+  DEFAULT_CURVED_STAIR_SWEEP_ANGLE,
+  DEFAULT_SPIRAL_SHOW_CENTER_COLUMN,
+  DEFAULT_SPIRAL_SHOW_STEP_SUPPORTS,
+  DEFAULT_SPIRAL_STAIR_SWEEP_ANGLE,
+  DEFAULT_SPIRAL_TOP_LANDING_DEPTH,
+  DEFAULT_SPIRAL_TOP_LANDING_MODE,
+  DEFAULT_STAIR_ATTACHMENT_SIDE,
+  DEFAULT_STAIR_FILL_TO_FLOOR,
+  DEFAULT_STAIR_HEIGHT,
+  DEFAULT_STAIR_LENGTH,
+  DEFAULT_STAIR_RAILING_HEIGHT,
+  DEFAULT_STAIR_RAILING_MODE,
+  DEFAULT_STAIR_STEP_COUNT,
+  DEFAULT_STAIR_THICKNESS,
+  DEFAULT_STAIR_TYPE,
+  DEFAULT_STAIR_WIDTH,
+} from './components/tools/stair/stair-defaults'
+export {
+  createWallOnCurrentLevel,
+  getSegmentGridStep,
+  isSegmentLongEnough,
+  snapPointToGrid,
+  snapScalarToGrid,
+  snapWallDraftPoint,
+  snapWallDraftPointDetailed,
+  WALL_FINE_GRID_STEP,
+  WALL_GRID_STEP,
+  type WallDraftSnapKind,
+  type WallDraftSnapResult,
+  type WallPlanPoint,
+} from './components/tools/wall/wall-drafting'
+// `ToolbarLeft` / `ToolbarRight` are the headless-spec aliases for the
+// existing `ViewerToolbarLeft` / `ViewerToolbarRight` exports — the
+// underlying components are the same; the alias just matches the names
+// used in `pascalorg/private-editor:plans/community-preset-system.md`
+// so consumer code stays close to the spec vocabulary.
+export {
+  CameraActions as ToolbarRight,
+  CameraActions as ViewerToolbarRight,
+} from './components/ui/action-menu/camera-actions'
+export {
+  ViewToggles as ToolbarLeft,
+  ViewToggles as ViewerToolbarLeft,
+} from './components/ui/action-menu/view-toggles'
 export { useCommandPalette } from './components/ui/command-palette'
+export { ActionButton, ActionGroup } from './components/ui/controls/action-button'
+export { MaterialPaintPanel } from './components/ui/controls/material-paint-panel'
+export { MaterialPicker } from './components/ui/controls/material-picker'
+export { MetricControl } from './components/ui/controls/metric-control'
+export { PanelSection } from './components/ui/controls/panel-section'
+export { SegmentedControl } from './components/ui/controls/segmented-control'
 export { SliderControl } from './components/ui/controls/slider-control'
+export { ToggleControl } from './components/ui/controls/toggle-control'
 export { FloatingLevelSelector } from './components/ui/floating-level-selector'
 export { CATALOG_ITEMS } from './components/ui/item-catalog/catalog-items'
+// Item collections UI — used by the kind-owned ItemPanel in nodes/.
+export { CollectionsPopover } from './components/ui/panels/collections/collections-popover'
+// Phase 5 Stage E — kinds with bespoke editors (slab holes list,
+// ceiling height presets, etc.) use `parametrics.customPanel` to mount
+// a kind-owned panel and need PanelWrapper for the chrome.
+export { PanelWrapper } from './components/ui/panels/panel-wrapper'
+export { ParametricInspector as Inspector } from './components/ui/panels/parametric-inspector'
+export { PALETTE_COLORS } from './components/ui/primitives/color-dot'
+export {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from './components/ui/primitives/dropdown-menu'
 export { useSidebarStore } from './components/ui/primitives/sidebar'
 export { Slider } from './components/ui/primitives/slider'
 export { SceneLoader } from './components/ui/scene-loader'
 export type { ExtraPanel } from './components/ui/sidebar/icon-rail'
+export { ItemsPanel } from './components/ui/sidebar/panels/items-panel'
+export type { FunctionTreeNode } from './components/ui/sidebar/panels/items-panel/function-tree-panel'
 export {
   type ProjectVisibility,
   SettingsPanel,
@@ -15,20 +164,110 @@ 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 { ViewerToolbarLeft, ViewerToolbarRight } from './components/ui/viewer-toolbar'
-export type { PresetsAdapter, PresetsTab } from './contexts/presets-context'
-export { PresetsProvider } from './contexts/presets-context'
 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)
+// can express their affordances declaratively in their own folder.
+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 { EDITOR_LAYER } from './lib/constants'
+// Helper libs used by the kind-owned roof / stair / elevator panels.
+export {
+  resolveCurrentBuildingId,
+  resolveElevatorNodeSupportY,
+  resolveElevatorSupportLevelId,
+  resolveElevatorSupportY,
+} from './lib/elevator-support'
+// Floor-plan stair helpers — the cumulative-transform walk
+// (`computeFloorplanStairSegmentTransforms`) and the rich segment-entry
+// builder (`buildFloorplanStairEntry`) used by the kind-owned stair
+// floor-plan emitter in `@pascal-app/nodes/src/stair/floorplan.ts`.
+// Each flight's transform depends on every prior sibling's length /
+// height / `attachmentSide`, so individual stair-segments can't compute
+// their own polygon in isolation — the stair (parent) owns the
+// computation and emits the whole stack as one registry entry.
+export {
+  alignFloorplanDraftPoint,
+  applyFloorplanAlignment,
+  buildFloorplanStairEntry,
+  FLOORPLAN_ALIGNMENT_THRESHOLD_M,
+  FLOORPLAN_DRAFT_ALIGN_ID,
+  type FloorplanAlignmentResult,
+  type FloorplanStairArrowEntry,
+  type FloorplanStairEntry,
+  type FloorplanStairSegmentEntry,
+  getFloorplanWallThickness,
+} from './lib/floorplan'
+export { commitFreshPlacementSubtree } from './lib/fresh-planar-placement'
+export {
+  buildResetSurfaceMaterialUpdates,
+  buildRoofSurfaceMaterialPatch,
+  buildSingleSurfaceMaterialPatch,
+  buildStairSurfaceMaterialPatch,
+  buildWallSurfaceMaterialPatch,
+  getActivePaintMaterialLabel,
+  hasActivePaintMaterial,
+} from './lib/material-paint'
+export {
+  addFreshPlacementMetadata,
+  getPlacementMetadataRecord,
+  isFreshPlacementMetadata,
+  stripPlacementMetadataFlags,
+} from './lib/placement-metadata'
+export {
+  type PlanarCursorPlacementMode,
+  type PlanarPoint,
+  resolvePlanarCursorPosition,
+} from './lib/planar-cursor-placement'
+export { clearRoofDuplicateMetadata, duplicateRoofSubtree } from './lib/roof-duplication'
 export type { SceneGraph } from './lib/scene'
 export { applySceneGraphToEditor } from './lib/scene'
 export { triggerSFX } from './lib/sfx-bus'
+export { duplicateStairSubtree } from './lib/stair-duplication'
+export {
+  getBuildingLevelsForLevel,
+  getStairLevelOptions,
+  resolveStairDestinationLevel,
+  resolveStairFromLevelId,
+  resolveStairPlacementLevelId,
+  resolveStairToLevelId,
+} from './lib/stair-levels'
+// `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,
+  resolveAlignmentForActiveBuilding,
+  snapBuildingLocalToWorldGrid,
+  snapWorldXZForActiveBuilding,
+} from './lib/world-grid-snap'
+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 { FloorplanSelectionTool, SplitOrientation, ViewMode } from './store/use-editor'
+export type {
+  FloorplanSelectionTool,
+  MovingFenceEndpoint,
+  MovingWallEndpoint,
+  SplitOrientation,
+  Tool,
+  ToolDefaults,
+  ViewMode,
+  WorkspaceMode,
+} from './store/use-editor'
 export { default as useEditor } from './store/use-editor'
 export {
   type PaletteView,
   type PaletteViewProps,
   usePaletteViewRegistry,
 } from './store/use-palette-view-registry'
+export { default as usePlacementPreview } from './store/use-placement-preview'
 export { useUploadStore } from './store/use-upload'
+export { useWallMoveGhosts, type WallMoveGhostBridge } from './store/use-wall-move-ghosts'
+export {
+  default as useWallSnapIndicator,
+  type WallSnapKind,
+  type WallSnapPoint,
+} from './store/use-wall-snap-indicator'

package/src/lib/constants.ts

@@ -1,3 +1,7 @@
+import { OVERLAY_LAYER } from '@pascal-app/viewer'
+
 /** Three.js layer used for editor-only objects (helpers, grid, polygon editors).
- *  The thumbnail camera renders only layer 0, so these are excluded from thumbnails. */
-export const EDITOR_LAYER = 1
+ *  The thumbnail camera renders only layer 0, so these are excluded from thumbnails.
+ *  Aliased to viewer's `OVERLAY_LAYER` so the post-processing overlay pass and the
+ *  editor's overlay meshes stay on the same layer. */
+export const EDITOR_LAYER = OVERLAY_LAYER

package/src/lib/editor-api.ts

@@ -0,0 +1,62 @@
+import type { AnyNode, EditorApi, FenceNode, WallNode } from '@pascal-app/core'
+import useEditor from '../store/use-editor'
+
+type EditorState = ReturnType<typeof useEditor.getState>
+type EndpointEngager = (node: AnyNode, endpoint: 'start' | 'end', editor: EditorState) => void
+
+/**
+ * Per-kind endpoint-move engagement. Kinds whose 2D endpoint drag
+ * needs its own store field (wall ↔ `movingWallEndpoint`, fence ↔
+ * `movingFenceEndpoint`) register their bridge here. The dispatcher
+ * is a table lookup rather than an `if (type === 'wall')` chain so
+ * adding a new endpoint-draggable kind is a one-line entry instead
+ * of a new branch. Each entry casts the generic `AnyNode` to its
+ * concrete kind — the lookup key already guarantees the type.
+ */
+const endpointEngagers: Record<string, EndpointEngager> = {
+  wall: (node, endpoint, editor) =>
+    editor.setMovingWallEndpoint({ wall: node as WallNode, endpoint }),
+  fence: (node, endpoint, editor) =>
+    editor.setMovingFenceEndpoint({ fence: node as FenceNode, endpoint }),
+}
+
+/**
+ * Concrete {@link EditorApi} backed by `useEditor`. Descriptors call into
+ * editor state through this interface; the editor owns the actual setter
+ * names so core stays decoupled.
+ *
+ * `engageMove` clears any in-progress endpoint drag or curve gesture so
+ * the move tool takes over cleanly — mirrors the legacy bookkeeping that
+ * lived inside `WallMoveArrowHandle.activateWallMove` / `FenceMoveArrowHandle`.
+ */
+export function createEditorApi(): EditorApi {
+  return {
+    engageMove(node: AnyNode) {
+      const editor = useEditor.getState()
+      editor.setPlacementDragMode(false)
+      // `setMovingNode` is typed against a narrower union than `AnyNode`
+      // (every concrete kind enumerated). Descriptors pass any node; the
+      // cast lets registry-driven move kinds through without forcing a
+      // schema-level type widening.
+      editor.setMovingNode(node as Parameters<typeof editor.setMovingNode>[0])
+      editor.setMovingWallEndpoint(null)
+      editor.setMovingFenceEndpoint(null)
+      editor.setCurvingWall(null)
+      editor.setCurvingFence(null)
+    },
+    engageMoveDrag(node: AnyNode) {
+      const editor = useEditor.getState()
+      // Flag drag mode BEFORE mounting the move tool so the coordinator reads
+      // it at setup and wires its commit-on-release listener.
+      editor.setPlacementDragMode(true)
+      editor.setMovingNode(node as Parameters<typeof editor.setMovingNode>[0])
+      editor.setMovingWallEndpoint(null)
+      editor.setMovingFenceEndpoint(null)
+      editor.setCurvingWall(null)
+      editor.setCurvingFence(null)
+    },
+    engageEndpointMove(node: AnyNode, endpoint: 'start' | 'end') {
+      endpointEngagers[node.type]?.(node, endpoint, useEditor.getState())
+    },
+  }
+}

package/src/lib/elevator-support.ts

@@ -0,0 +1,96 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  type BuildingNode,
+  type ElevatorNode,
+  type LevelNode,
+  spatialGridManager,
+  useScene,
+} from '@pascal-app/core'
+
+function getBuildingLevels(
+  buildingId: string | null | undefined,
+  nodes: Record<string, AnyNode>,
+): LevelNode[] {
+  if (!buildingId) return []
+  const building = nodes[buildingId as AnyNodeId]
+  if (building?.type !== 'building') return []
+
+  return building.children
+    .map((childId) => nodes[childId as AnyNodeId])
+    .filter((entry): entry is LevelNode => entry?.type === 'level')
+    .sort((left, right) => left.level - right.level)
+}
+
+export function resolveCurrentBuildingId({
+  buildingId,
+  levelId,
+  nodes,
+}: {
+  buildingId: BuildingNode['id'] | null
+  levelId: LevelNode['id'] | null
+  nodes: Record<string, AnyNode>
+}): BuildingNode['id'] | null {
+  if (buildingId) return buildingId
+  if (!levelId) return null
+
+  const level = nodes[levelId as AnyNodeId]
+  if (
+    level?.type === 'level' &&
+    level.parentId &&
+    nodes[level.parentId as AnyNodeId]?.type === 'building'
+  ) {
+    return level.parentId as BuildingNode['id']
+  }
+
+  return null
+}
+
+export function resolveElevatorSupportLevelId({
+  buildingId,
+  preferredLevelId,
+}: {
+  buildingId: string | null | undefined
+  preferredLevelId?: string | null
+}): LevelNode['id'] | null {
+  const nodes = useScene.getState().nodes
+  const preferred = preferredLevelId ? nodes[preferredLevelId as AnyNodeId] : undefined
+  const levels = getBuildingLevels(buildingId, nodes)
+  const preferredInBuilding = preferredLevelId
+    ? levels.find((level) => level.id === preferredLevelId)
+    : undefined
+
+  if (preferredInBuilding) return preferredInBuilding.id
+  if (levels.length === 0) return preferred?.type === 'level' ? preferred.id : null
+
+  return levels[0]?.id ?? null
+}
+
+export function resolveElevatorSupportY({
+  buildingId,
+  preferredLevelId,
+  x,
+  z,
+}: {
+  buildingId: string | null | undefined
+  preferredLevelId?: string | null
+  x: number
+  z: number
+}): number {
+  const levelId = resolveElevatorSupportLevelId({ buildingId, preferredLevelId })
+  if (!levelId) return 0
+
+  return Math.max(0, spatialGridManager.getSlabElevationAt(levelId, x, z))
+}
+
+export function resolveElevatorNodeSupportY(
+  node: ElevatorNode,
+  position: [number, number, number] = node.position,
+): number {
+  return resolveElevatorSupportY({
+    buildingId: node.parentId,
+    preferredLevelId: node.fromLevelId ?? node.defaultLevelId,
+    x: position[0],
+    z: position[2],
+  })
+}

package/src/lib/floorplan/apply-alignment.ts

@@ -0,0 +1,111 @@
+import {
+  type AlignmentAnchor,
+  type AlignmentGuide,
+  collectAlignmentAnchors,
+  resolveAlignment,
+  useScene,
+} from '@pascal-app/core'
+import { useAlignmentGuides } from '@pascal-app/editor'
+
+/**
+ * Fixed Figma-style alignment threshold (meters) for floor-plan placement /
+ * move — parity with the 3D tools' `ALIGNMENT_THRESHOLD_M`. Pure-2D drafting
+ * can pass a zoom-scaled `threshold` instead so the magnetic pull stays
+ * constant in screen pixels across zoom levels.
+ */
+export const FLOORPLAN_ALIGNMENT_THRESHOLD_M = 0.08
+
+export type FloorplanAlignmentResult = {
+  /** Plan point with the alignment snap delta applied (grid snap should
+   *  already be baked into the input point). */
+  point: [number, number]
+  snapped: boolean
+  guides: AlignmentGuide[]
+}
+
+/**
+ * Layer Figma-style alignment on top of an already grid-snapped plan point,
+ * shared by the 2D move sessions (`*FloorplanMoveTarget`) and the structural
+ * drafting branches in `floorplan-panel`.
+ *
+ * Publishes guides to the `useAlignmentGuides` store as a side effect — set
+ * on a match, cleared otherwise — so the mounted `FloorplanAlignmentGuideLayer`
+ * renders them. Returns the adjusted point. When `bypass` is true (Alt held)
+ * the point is returned unchanged and guides are cleared, matching the
+ * "No snap" affordance the placement tools advertise.
+ *
+ * `candidates` should be gathered ONCE per drag (`collectAlignmentAnchors`);
+ * the scene is stable during a single drag, so re-collecting per pointer-move
+ * is wasted work.
+ */
+export function applyFloorplanAlignment(
+  point: readonly [number, number],
+  movingAnchors: AlignmentAnchor[],
+  candidates: AlignmentAnchor[],
+  opts?: { bypass?: boolean; threshold?: number },
+): FloorplanAlignmentResult {
+  if (opts?.bypass) {
+    useAlignmentGuides.getState().clear()
+    return { point: [point[0], point[1]], snapped: false, guides: [] }
+  }
+
+  const result = resolveAlignment({
+    moving: movingAnchors,
+    candidates,
+    threshold: opts?.threshold ?? FLOORPLAN_ALIGNMENT_THRESHOLD_M,
+  })
+
+  useAlignmentGuides.getState().set(result.guides)
+
+  if (!result.snap) {
+    return { point: [point[0], point[1]], snapped: false, guides: result.guides }
+  }
+  return {
+    point: [point[0] + result.snap.dx, point[1] + result.snap.dz],
+    snapped: true,
+    guides: result.guides,
+  }
+}
+
+/** Synthetic node id for the in-progress structural-draft vertex. Never
+ *  collides with a real scene node, so `collectAlignmentAnchors` excludes
+ *  nothing real. */
+export const FLOORPLAN_DRAFT_ALIGN_ID = '__floorplan_draft__'
+
+/**
+ * Align a single grid-snapped structural-draft vertex (wall / fence / polygon
+ * / roof endpoint) against every other node's anchors (incl. wall faces from
+ * the wall-face anchor work). Treats the vertex as one corner anchor, gathers
+ * candidates from the live scene, publishes guides (cleared on `bypass`), and
+ * returns the possibly-snapped point.
+ *
+ * Used by BOTH the move-preview branch and the click-commit handler so the
+ * committed vertex lands exactly where the preview showed it. Caller owns the
+ * per-kind precedence (existing-wall endpoint/join snap wins; angle-snap
+ * suppresses alignment) and only calls this when alignment should apply.
+ *
+ * `excludeIds` drops those nodes' anchors from the candidate pool — used when
+ * dragging a wall / fence endpoint so the moving endpoint doesn't try to
+ * align to its own (and its linked siblings') geometry that moves with it.
+ */
+export function alignFloorplanDraftPoint(
+  point: readonly [number, number],
+  opts?: { bypass?: boolean; threshold?: number; excludeIds?: readonly string[] },
+): [number, number] {
+  if (opts?.bypass) {
+    useAlignmentGuides.getState().clear()
+    return [point[0], point[1]]
+  }
+  let candidates = collectAlignmentAnchors(useScene.getState().nodes, FLOORPLAN_DRAFT_ALIGN_ID)
+  if (opts?.excludeIds?.length) {
+    const excluded = new Set(opts.excludeIds)
+    candidates = candidates.filter((anchor) => !excluded.has(anchor.nodeId))
+  }
+  const { point: snapped } = applyFloorplanAlignment(
+    point,
+    [{ nodeId: FLOORPLAN_DRAFT_ALIGN_ID, kind: 'corner', x: point[0], z: point[1] }],
+    candidates,
+    { threshold: opts?.threshold },
+  )
+  return snapped
+}

package/src/lib/floorplan/index.ts

@@ -1,3 +1,10 @@
+export {
+  alignFloorplanDraftPoint,
+  applyFloorplanAlignment,
+  FLOORPLAN_ALIGNMENT_THRESHOLD_M,
+  FLOORPLAN_DRAFT_ALIGN_ID,
+  type FloorplanAlignmentResult,
+} from './apply-alignment'
 export {
   clampPlanValue,
   doesPolygonIntersectSelectionBounds,