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

package/src/store/use-editor.tsx

@@ -4,11 +4,15 @@ import type { AssetInput } from '@pascal-app/core'
 import {
   type AnyNode,
   type AnyNodeId,
+  type BrushSettings,
   type BuildingNode,
+  type CabinetModuleNode,
+  type CabinetNode,
   type CeilingNode,
   type ChimneyMaterialRole,
   type ChimneyNode,
   type ColumnNode,
+  DEFAULT_BRUSH_SETTINGS,
   type DoorNode,
   type DormerNode,
   type DormerSurfaceMaterialRole,
@@ -16,6 +20,7 @@ import {
   type FenceNode,
   type ItemNode,
   type LevelNode,
+  nodeRegistry,
   type RoofNode,
   type RoofSegmentNode,
   type RoofSurfaceMaterialRole,
@@ -25,6 +30,7 @@ import {
   type StairNode,
   type StairSegmentNode,
   type StairSurfaceMaterialRole,
+  type TerrainVerb,
   useScene,
   type WallNode,
   type WallSurfaceSide,
@@ -33,6 +39,13 @@ import {
 import { useViewer } from '@pascal-app/viewer'
 import { create } from 'zustand'
 import { persist } from 'zustand/middleware'
+import {
+  CONTINUATION_PROFILES,
+  type ContinuationContext,
+  type ContinuationMode,
+  continuationContextOf,
+  nextContinuation,
+} from '../lib/continuation'
 import {
   type ActivePaintMaterial,
   type PaintableMaterialTarget,
@@ -40,12 +53,58 @@ import {
   resolvePaintTargetFromSelection,
   type SingleSurfaceMaterialRole,
 } from '../lib/material-paint'
-
-const DEFAULT_ACTIVE_SIDEBAR_PANEL = 'ai'
+import {
+  type CreatableMeasurementKind,
+  DEFAULT_CREATABLE_MEASUREMENT_KIND,
+  normalizeCreatableMeasurementKind,
+} from '../lib/measurement-kind'
+import {
+  cyclePaintScope as cyclePaintScopeValue,
+  type PaintHoverInfo,
+  type PaintScope,
+} from '../lib/paint-scope'
+import {
+  cycleSnappingModeIn,
+  defaultSnappingModeFor,
+  resolveSnapFlags,
+  type SnapContext,
+  type SnappingMode,
+  snapContextOf,
+  snappingModesFor,
+} from '../lib/snapping-mode'
+import { publishNavigationSyncPoseToStore } from './navigation-sync-pose-store'
+import useInteractionScope from './use-interaction-scope'
+
+const DEFAULT_ACTIVE_SIDEBAR_PANEL = 'build'
 const DEFAULT_FLOORPLAN_PANE_RATIO = 0.5
 const MIN_FLOORPLAN_PANE_RATIO = 0.15
 const MAX_FLOORPLAN_PANE_RATIO = 0.85
 
+function resolveMovingNodeTarget(
+  node:
+    | ItemNode
+    | WindowNode
+    | DoorNode
+    | ElevatorNode
+    | CeilingNode
+    | ChimneyNode
+    | ColumnNode
+    | DormerNode
+    | SlabNode
+    | WallNode
+    | FenceNode
+    | RoofNode
+    | RoofSegmentNode
+    | SpawnNode
+    | StairNode
+    | StairSegmentNode
+    | BuildingNode
+    | CabinetNode
+    | CabinetModuleNode,
+) {
+  return node
+}
+
 export type ViewMode = '3d' | '2d' | 'split'
 export type SplitOrientation = 'horizontal' | 'vertical'
 export type WorkspaceMode = 'edit' | 'studio'
@@ -59,9 +118,16 @@ export type WorkspaceMode = 'edit' | 'studio'
 // — `ThumbnailGenerator` consults `captureMode.mode === 'preset'` and
 // applies those constraints. Keeping it a discriminated union lets us
 // add future modes without surfacing the choice to end users.
+// How the captured pixels are cropped: full-frame 16:9, raw canvas viewport,
+// or user-dragged area. Hosts (e.g. the studio capture bar) can preselect it
+// when entering capture mode.
+export type SnapshotCropMode = 'standard' | 'viewport' | 'area'
+/** Aspect presets available to `standard` crops. */
+export type SnapshotStandardAspect = '16:9' | '9:16' | '4:3' | '3:4' | '1:1'
+
 export type CaptureMode =
   | { mode: 'idle' }
-  | { mode: 'standard' }
+  | { mode: 'standard'; crop?: SnapshotCropMode; standardAspect?: SnapshotStandardAspect }
   | {
       mode: 'preset'
       isolated: AnyNodeId[]
@@ -75,10 +141,24 @@ export type CaptureMode =
 
 export type Phase = 'site' | 'structure' | 'furnish'
 
-export type Mode = 'select' | 'edit' | 'delete' | 'build' | 'material-paint'
+/**
+ * `terrain-sculpt` is a mode, not a build tool, and that is the whole answer to
+ * "how does terrain editing avoid conflicting with everything else".
+ *
+ * A build tool places a node and hands the pointer back. Sculpting is a
+ * sustained brush over the *ground* — the one surface every other tool uses as
+ * its reference plane — so while it is armed, clicks must not select a wall,
+ * drag a window, or arm a ghost. Modeling it as a mode gets that for free: it is
+ * mutually exclusive with `build`/`select`/`delete` by construction, every
+ * selection manager already early-returns unless `mode === 'select'`, and it
+ * holds a `sculpting` interaction scope for its whole lifetime so conflicting
+ * controls stay stepped back. `material-paint` is the existing precedent for
+ * exactly this shape.
+ */
+export type Mode = 'select' | 'edit' | 'delete' | 'build' | 'material-paint' | 'terrain-sculpt'
 
 // Structure mode tools (building elements)
-export type StructureTool =
+type BuiltInStructureTool =
   | 'wall'
   | 'fence'
   | 'room'
@@ -87,6 +167,7 @@ export type StructureTool =
   | 'ceiling'
   | 'roof'
   | 'column'
+  | 'structural-grid'
   | 'elevator'
   | 'stair'
   | 'item'
@@ -106,9 +187,21 @@ export type StructureTool =
   | 'dormer'
   | 'gutter'
   | 'downspout'
+  | 'duct-segment'
+  | 'duct-fitting'
+  | 'duct-terminal'
+  | 'hvac-equipment'
+  | 'lineset'
+  | 'liquid-line'
+  | 'pipe-segment'
+  | 'pipe-fitting'
+  | 'pipe-trap'
+
+/** Registry node kinds are valid build tools without central union edits. */
+export type StructureTool = BuiltInStructureTool | (string & {})
 
 // Furnish mode tools (items and decoration)
-export type FurnishTool = 'item'
+export type FurnishTool = 'item' | 'cabinet'
 
 // Site mode tools
 export type SiteTool = 'property-line'
@@ -140,8 +233,14 @@ export type NavigationSyncPose = {
 
 export type NavigationSyncPoseInput = Omit<NavigationSyncPose, 'revision'>
 
-// Combined tool type
-export type Tool = SiteTool | StructureTool | FurnishTool
+// Combined tool type. Known literals keep autocomplete; the `(string & {})`
+// arm lets plugin-contributed tool ids (e.g. `'trees:tree'`) typecheck without
+// the host enumerating every plugin kind. The runtime dispatch is already
+// registry-first — `tool-manager` resolves `nodeRegistry.get(tool)?.tool` — so
+// an unknown-to-the-host tool string flows straight through to the plugin's
+// placement component.
+export type KnownTool = SiteTool | StructureTool | FurnishTool
+export type Tool = KnownTool | (string & {})
 
 /**
  * Starting parameters seeded into a draw tool before it mints a node.
@@ -151,16 +250,6 @@ export type Tool = SiteTool | StructureTool | FurnishTool
  */
 export type ToolDefaults = Record<string, unknown>
 
-export type MovingWallEndpoint = {
-  wall: WallNode
-  endpoint: 'start' | 'end'
-}
-
-export type MovingFenceEndpoint = {
-  fence: FenceNode
-  endpoint: 'start' | 'end'
-}
-
 export type MaterialTargetRole =
   | WallSurfaceSide
   | StairSurfaceMaterialRole
@@ -168,6 +257,7 @@ export type MaterialTargetRole =
   | ChimneyMaterialRole
   | DormerSurfaceMaterialRole
   | SingleSurfaceMaterialRole
+  | string
 
 export type SelectedMaterialTarget = {
   nodeId: AnyNodeId
@@ -203,31 +293,14 @@ type EditorState = {
    */
   toolDefaults: Partial<Record<Tool, ToolDefaults>>
   setToolDefaults: (tool: Tool, defaults: ToolDefaults | null) => void
+  lastMeasurementKind: CreatableMeasurementKind
+  setLastMeasurementKind: (kind: CreatableMeasurementKind) => void
   structureLayer: StructureLayer
   setStructureLayer: (layer: StructureLayer) => void
   catalogCategory: CatalogCategory | null
   setCatalogCategory: (category: CatalogCategory | null) => void
   selectedItem: AssetInput | null
   setSelectedItem: (item: AssetInput) => void
-  movingNode:
-    | ItemNode
-    | WindowNode
-    | DoorNode
-    | ElevatorNode
-    | CeilingNode
-    | ChimneyNode
-    | ColumnNode
-    | DormerNode
-    | SlabNode
-    | WallNode
-    | FenceNode
-    | RoofNode
-    | RoofSegmentNode
-    | SpawnNode
-    | StairNode
-    | StairSegmentNode
-    | BuildingNode
-    | null
   /**
    * True while a move was engaged by a press-drag gizmo (the on-canvas move
    * cross) rather than a click-to-place flow. The placement coordinator reads
@@ -235,6 +308,8 @@ type EditorState = {
    */
   placementDragMode: boolean
   setPlacementDragMode: (dragMode: boolean) => void
+  roofHostDragArmedId: AnyNodeId | null
+  setRoofHostDragArmedId: (nodeId: AnyNodeId | null) => void
   setMovingNode: (
     node:
       | ItemNode
@@ -254,6 +329,8 @@ type EditorState = {
       | StairNode
       | StairSegmentNode
       | BuildingNode
+      | CabinetNode
+      | CabinetModuleNode
       | null,
   ) => void
   /**
@@ -275,43 +352,80 @@ type EditorState = {
    */
   movingNodeOrigin: '2d' | '3d' | null
   setMovingNodeOrigin: (origin: '2d' | '3d' | null) => void
-  movingWallEndpoint: MovingWallEndpoint | null
-  setMovingWallEndpoint: (value: MovingWallEndpoint | null) => void
-  movingFenceEndpoint: MovingFenceEndpoint | null
-  setMovingFenceEndpoint: (value: MovingFenceEndpoint | null) => void
   /**
-   * Generic per-kind handle drag state. Set by a node's resize handle
-   * (height arrow, width arrow, rise / sweep / inner-radius for curved
-   * stairs, …) at drag-start and cleared on drag-end. `label`
-   * identifies which dimension the handle controls — measurement
-   * overlays read it to render the right caption; the camera controls
-   * use the truthy value to suppress one-finger pan-rotate. Replaces
-   * the previous per-kind `resizing*` fields so adding a new resize
-   * handle doesn't require a new store field.
+   * World axis the R/T keyboard rotation turns around, for kinds with
+   * full 3D orientation (duct fittings). Alt cycles it Y → X → Z; the
+   * kind's tool / keyboard actions read it, and the floating action
+   * menu surfaces it in a pill above the selected node.
    */
-  activeHandleDrag: { nodeId: AnyNodeId; label: string } | null
-  setActiveHandleDrag: (drag: { nodeId: AnyNodeId; label: string } | null) => void
-  curvingWall: WallNode | null
-  setCurvingWall: (wall: WallNode | null) => void
-  curvingFence: FenceNode | null
-  setCurvingFence: (fence: FenceNode | null) => void
+  rotationAxis: 'x' | 'y' | 'z'
+  cycleRotationAxis: () => 'x' | 'y' | 'z'
   selectedMaterialTarget: SelectedMaterialTarget | null
   setSelectedMaterialTarget: (target: SelectedMaterialTarget | null) => void
   activePaintMaterial: ActivePaintMaterial | null
   setActivePaintMaterial: (material: ActivePaintMaterial | null) => void
   activePaintTarget: PaintableMaterialTarget
   setActivePaintTarget: (target: PaintableMaterialTarget) => void
+  // Live vertex count of an in-progress polygon draft (slab / ceiling), so the
+  // contextual HUD can gate hints on it (e.g. "Finish" only once ≥ 3 points).
+  // 0 when not drafting. Not persisted.
+  draftVertexCount: number
+  setDraftVertexCount: (count: number) => void
+  // Painter application scope — how far one paint click spreads (this surface /
+  // whole item / all matching / room). One global mode, target-aware in the HUD
+  // (see `lib/paint-scope.ts`), defaulting to the narrowest `'single'`. Not
+  // persisted: a "paint everything" scope should reset each session.
+  paintScope: PaintScope
+  setPaintScope: (scope: PaintScope) => void
+  // Cycle the scope within the hovered node's available set and return the new
+  // value. Bound to Shift while in paint mode.
+  cyclePaintScope: () => PaintScope
   // When true, clicking a surface in paint mode clears it back to its
   // default material instead of applying `activePaintMaterial`.
   paintEraser: boolean
   setPaintEraser: (eraser: boolean) => void
   primeMaterialPaintFromSelection: () => MaterialPaintSelectionSnapshot
-  hoveredPaintTarget: PaintableMaterialTarget | null
-  setHoveredPaintTarget: (target: PaintableMaterialTarget | null) => void
-  isPaintPanelOpen: boolean
-  setPaintPanelOpen: (open: boolean) => void
+  /**
+   * Terrain sculpt state. Lives here rather than in the tool component so the
+   * bottom-bar HUD, the keyboard shortcuts, and the brush all read one source —
+   * the same reason the paint mode's material/scope/eraser live here.
+   */
+  terrainVerb: TerrainVerb
+  setTerrainVerb: (verb: TerrainVerb) => void
+  terrainBrush: BrushSettings
+  setTerrainBrush: (settings: Partial<BrushSettings>) => void
+  /**
+   * Absolute height in metres the `flatten` verb aims at. Sampled by clicking
+   * the ground with the eyedropper, or typed. `null` means "sample on first
+   * click", which is what makes flatten usable without ever opening a number
+   * field.
+   */
+  terrainFlattenTarget: number | null
+  setTerrainFlattenTarget: (metres: number | null) => void
+  /**
+   * True while the next click should sample a flatten target instead of
+   * sculpting. One-shot: sampling clears it.
+   */
+  terrainSampling: boolean
+  setTerrainSampling: (sampling: boolean) => void
+  // What the cursor is over in paint mode: the scopes it offers + labels for the
+  // HUD chip. `null` when not over a paintable surface (drives the "hover a
+  // surface" hint). Set by the selection-manager paint hover; not persisted.
+  paintHover: PaintHoverInfo | null
+  setPaintHover: (info: PaintHoverInfo | null) => void
+  // Embedder capability: true when a host (e.g. community) can locate a selected
+  // node in its catalog browser. Gates the node action menu's "Find" button; the
+  // editor itself emits `selection:find-node` and lets the host fulfil it. Not
+  // persisted — it's a per-mount capability the host registers.
+  canFindNode: boolean
+  setCanFindNode: (canFind: boolean) => void
   selectedReferenceId: string | null
   setSelectedReferenceId: (id: string | null) => void
+  // Guide id with an in-flight reference-scale measurement (line drawing or
+  // length dialog). Owned by the floorplan panel; mirrored here so the
+  // reference panel can flip its Set Scale button into a Cancel.
+  referenceScaleActiveGuideId: string | null
+  setReferenceScaleActiveGuideId: (id: string | null) => void
   guideUi: Record<string, GuideUiState>
   setGuideLocked: (guideId: string, locked: boolean) => void
   setGuideScaleReferenceVisible: (guideId: string, visible: boolean) => void
@@ -319,9 +433,6 @@ type EditorState = {
   // Space detection for cutaway mode
   spaces: Record<string, Space>
   setSpaces: (spaces: Record<string, Space>) => void
-  // Generic hole editing (works for slabs, ceilings, and any future polygon nodes)
-  editingHole: SurfaceHoleTarget | null
-  setEditingHole: (hole: SurfaceHoleTarget | null) => void
   hoveredHole: SurfaceHoleTarget | null
   setHoveredHole: (hole: SurfaceHoleTarget | null) => void
   // Preview mode (viewer-like experience inside the editor)
@@ -348,17 +459,38 @@ type EditorState = {
   toggleFloorplanOpen: () => void
   isFloorplanHovered: boolean
   setFloorplanHovered: (hovered: boolean) => void
+  // Toggleable DWV riser-diagram (plumbing isometric) overlay.
+  isRiserOpen: boolean
+  setRiserOpen: (open: boolean) => void
+  toggleRiserOpen: () => void
   navigationSyncPose: NavigationSyncPose | null
   publishNavigationSyncPose: (pose: NavigationSyncPoseInput) => void
   floorplanSelectionTool: FloorplanSelectionTool
   setFloorplanSelectionTool: (tool: FloorplanSelectionTool) => void
   gridSnapStep: GridSnapStep
   setGridSnapStep: (step: GridSnapStep) => void
+  // Cycles the grid step through GRID_SNAP_STEPS (0.5 → 0.25 → 0.1 → 0.05 →
+  // 0.5) and returns the new value. Bound to the measurement-step shortcut.
+  cycleGridSnapStep: () => GridSnapStep
   // Magnetic snapping while drafting — snaps wall endpoints onto existing
   // wall corners / wall bodies (the "magnetic" beacon). Independent of grid
   // snap. On by default; toggled from the Display menu.
   magneticSnap: boolean
   setMagneticSnap: (enabled: boolean) => void
+  // Per-context, user-cyclable snapping mode (see `lib/snapping-mode.ts`). Each
+  // activity (wall / item / polygon) keeps its own mode + default, because they
+  // want different snapping — drawing a wall wants grid + angle, nudging an item
+  // wants free movement that only catches alignment lines. Resolved to the live
+  // context via `getActiveSnappingMode()`; maps onto `gridSnapStep`/`magneticSnap`
+  // via `resolveSnapFlags`. Persisted per context.
+  snappingModeByContext: Record<SnapContext, SnappingMode>
+  setSnappingMode: (context: SnapContext, mode: SnappingMode) => void
+  // Cycle the *active* context's mode within its own set; returns the new value.
+  cycleSnappingMode: () => SnappingMode
+  continuationByContext: Record<ContinuationContext, ContinuationMode>
+  setContinuation: (context: ContinuationContext, mode: ContinuationMode) => void
+  cycleContinuation: (context: ContinuationContext) => ContinuationMode
+  getContinuation: (context: ContinuationContext) => ContinuationMode
   showReferenceFloor: boolean
   toggleReferenceFloor: () => void
   setShowReferenceFloor: (show: boolean) => void
@@ -369,6 +501,11 @@ type EditorState = {
   // Development-only camera debug flag for inspecting underside geometry
   allowUndergroundCamera: boolean
   setAllowUndergroundCamera: (enabled: boolean) => void
+  // Development-only debug overlay: draw each wall's opening-snap hit area
+  // (the capsule of points within the snap radius of its centerline). Lets us
+  // see why a door/window snaps where it does.
+  show2dVoronoi: boolean
+  setShow2dVoronoi: (enabled: boolean) => void
   // First-person walkthrough mode (street view)
   isFirstPersonMode: boolean
   _viewModeBeforeFirstPerson: ViewMode | null
@@ -402,6 +539,9 @@ type PersistedEditorLayoutState = Pick<
   | 'floorplanSelectionTool'
   | 'gridSnapStep'
   | 'magneticSnap'
+  | 'lastMeasurementKind'
+  | 'snappingModeByContext'
+  | 'continuationByContext'
   | 'showReferenceFloor'
   | 'referenceFloorOffset'
   | 'referenceFloorOpacity'
@@ -425,6 +565,18 @@ export const DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE: PersistedEditorLayoutState =
   floorplanSelectionTool: 'click',
   gridSnapStep: 0.5,
   magneticSnap: true,
+  lastMeasurementKind: DEFAULT_CREATABLE_MEASUREMENT_KIND,
+  snappingModeByContext: {
+    wall: defaultSnappingModeFor('wall'),
+    item: defaultSnappingModeFor('item'),
+    polygon: defaultSnappingModeFor('polygon'),
+  },
+  continuationByContext: {
+    wall: CONTINUATION_PROFILES.wall.default,
+    fence: CONTINUATION_PROFILES.fence.default,
+    point: CONTINUATION_PROFILES.point.default,
+    cabinet: CONTINUATION_PROFILES.cabinet.default,
+  },
   showReferenceFloor: false,
   referenceFloorOffset: 1,
   referenceFloorOpacity: 0.35,
@@ -437,8 +589,12 @@ type SelectDefaultBuildingAndLevelOptions = {
 }
 
 function normalizeModeForPhase(phase: Phase, mode: Mode | undefined): Mode {
+  // The site phase used to hard-return `select`, which made a site-phase brush
+  // mode unrepresentable. It is an allowlist now rather than a free-for-all:
+  // `delete` and `material-paint` still have nothing to act on at site scope, so
+  // letting them survive here would restore a mode with no targets.
   if (phase === 'site') {
-    return 'select'
+    return mode === 'terrain-sculpt' ? mode : 'select'
   }
 
   return mode === 'build' || mode === 'delete' || mode === 'material-paint' ? mode : 'select'
@@ -456,7 +612,7 @@ export function normalizePersistedEditorUiState(
   state: Partial<PersistedEditorUiState> | null | undefined,
 ): PersistedEditorUiState {
   const phase = state?.phase === 'structure' || state?.phase === 'furnish' ? state.phase : 'site'
-  const mode = normalizeModeForPhase(phase, state?.mode)
+  let mode = normalizeModeForPhase(phase, state?.mode)
 
   // Migrate old isFloorplanOpen to viewMode
   let viewMode: ViewMode = '3d'
@@ -467,6 +623,13 @@ export function normalizePersistedEditorUiState(
   }
   const isFloorplanOpen = viewMode !== '3d'
 
+  // Both are persisted independently, and rehydrate goes through neither setter,
+  // so this is the third place the sculpt/2D pair has to be reconciled. The view
+  // wins here for the same reason it does in `setViewMode`: a brush armed over a
+  // hidden canvas is a mode the user cannot use, and reviving one on load is
+  // worse than reviving it mid-session — nothing on screen explains it.
+  if (mode === 'terrain-sculpt' && viewMode === '2d') mode = 'select'
+
   if (phase === 'site') {
     return {
       ...DEFAULT_PERSISTED_EDITOR_UI_STATE,
@@ -527,8 +690,51 @@ export function normalizePersistedEditorUiState(
   }
 }
 
+// Validate a persisted per-context mode against that context's allowed set
+// (so e.g. a stale `angles` for items resets), falling back to its default.
+function migrateSnappingMode(value: unknown, context: SnapContext): SnappingMode {
+  return snappingModesFor(context).includes(value as SnappingMode)
+    ? (value as SnappingMode)
+    : defaultSnappingModeFor(context)
+}
+
+type LegacyContinuationState = {
+  continuationByContext?: Partial<Record<ContinuationContext, unknown>>
+  wallChainMode?: unknown
+  fenceChainMode?: unknown
+}
+
+function migrateContinuationMode(
+  value: unknown,
+  context: ContinuationContext,
+): ContinuationMode | null {
+  const profile = CONTINUATION_PROFILES[context]
+  return profile.options.includes(value as ContinuationMode) ? (value as ContinuationMode) : null
+}
+
+function normalizeContinuationByContext(
+  state: LegacyContinuationState | null | undefined,
+): Record<ContinuationContext, ContinuationMode> {
+  return {
+    wall:
+      migrateContinuationMode(state?.continuationByContext?.wall, 'wall') ??
+      migrateContinuationMode(state?.wallChainMode, 'wall') ??
+      CONTINUATION_PROFILES.wall.default,
+    fence:
+      migrateContinuationMode(state?.continuationByContext?.fence, 'fence') ??
+      migrateContinuationMode(state?.fenceChainMode, 'fence') ??
+      CONTINUATION_PROFILES.fence.default,
+    point:
+      migrateContinuationMode(state?.continuationByContext?.point, 'point') ??
+      CONTINUATION_PROFILES.point.default,
+    cabinet:
+      migrateContinuationMode(state?.continuationByContext?.cabinet, 'cabinet') ??
+      CONTINUATION_PROFILES.cabinet.default,
+  }
+}
+
 function normalizePersistedEditorLayoutState(
-  state: Partial<PersistedEditorLayoutState> | null | undefined,
+  state: (Partial<PersistedEditorLayoutState> & LegacyContinuationState) | null | undefined,
 ): PersistedEditorLayoutState {
   return {
     activeSidebarPanel:
@@ -543,6 +749,13 @@ function normalizePersistedEditorLayoutState(
       : DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.gridSnapStep,
     // Default on: only an explicit persisted `false` disables it.
     magneticSnap: state?.magneticSnap !== false,
+    lastMeasurementKind: normalizeCreatableMeasurementKind(state?.lastMeasurementKind),
+    snappingModeByContext: {
+      wall: migrateSnappingMode(state?.snappingModeByContext?.wall, 'wall'),
+      item: migrateSnappingMode(state?.snappingModeByContext?.item, 'item'),
+      polygon: migrateSnappingMode(state?.snappingModeByContext?.polygon, 'polygon'),
+    },
+    continuationByContext: normalizeContinuationByContext(state),
     showReferenceFloor: state?.showReferenceFloor === true,
     referenceFloorOffset:
       typeof state?.referenceFloorOffset === 'number' && state.referenceFloorOffset >= 1
@@ -662,6 +875,59 @@ export function selectSiteFloorplanContext() {
   })
 }
 
+// Stashes the view mode the user was in before entering capture, so we can
+// restore it on exit. Snapshot capture always frames in 3D — the 2D/split
+// floorplan panes render nothing meaningful for a thumbnail.
+let viewModeBeforeCapture: ViewMode | null = null
+
+/**
+ * Hold the interaction scope that belongs to a sustained brush mode.
+ *
+ * Paint and sculpt are the two modes whose scope lifetime is the *mode*, not a
+ * pointer gesture. Both must be released whenever the mode changes for any
+ * reason — including the phase switch that resets the mode without going through
+ * `setMode`. A stuck `sculpting` scope would leave selection disabled across the
+ * whole editor, so this is one function called from every mode transition rather
+ * than a rule each transition remembers.
+ *
+ * The eyedropper arm rides along for the same reason: it is one-shot state whose
+ * UI is unmounted the moment sculpt mode ends, so it has to be cleared on every
+ * exit path and not just the one through `setMode`.
+ *
+ * Every `set({ mode: ... })` in this store must be followed by a call to this —
+ * see the callers in `setPhase`, `setStructureLayer`, `setPreviewMode`,
+ * `setFirstPersonMode` and `setWorkspaceMode`. The four view-swapping ones are
+ * the dangerous class: they unmount `ToolManager` (via `noEditing`), so the
+ * sculpt tool that would otherwise release the scope on unmount is gone, and a
+ * scope leaked there is unrecoverable without a reload.
+ */
+function syncBrushModeScope(mode: Mode): void {
+  const scope = useInteractionScope.getState()
+  if (mode === 'material-paint') scope.begin({ kind: 'painting' })
+  else if (mode === 'terrain-sculpt') scope.begin({ kind: 'sculpting' })
+  // `isBrushMode` is the same set as the two branches above — kept as one
+  // predicate so an added brush mode cannot be handled here and missed there.
+  else {
+    scope.endIf((s) => s.kind === 'painting' || s.kind === 'sculpting')
+    if (useEditor.getState().terrainSampling) useEditor.getState().setTerrainSampling(false)
+  }
+}
+
+/**
+ * Whether `mode` is one of the two sustained brush modes.
+ *
+ * Named because callers *outside* this store need the same test: a scope is
+ * single-owner, so anything that calls `begin()` while a brush mode holds its
+ * scope silently evicts it — the brush stays armed and painting while the rest of
+ * the editor believes a drag is running. Almost every producer is unreachable
+ * under a brush mode because it needs a selection and entering the mode clears
+ * one, but the clipboard paths read the clipboard instead (see
+ * `pasteSelectionAndPickUp`), so they have to ask.
+ */
+export function isBrushMode(mode: Mode): boolean {
+  return mode === 'material-paint' || mode === 'terrain-sculpt'
+}
+
 const useEditor = create<EditorState>()(
   persist(
     (set, get) => ({
@@ -690,6 +956,11 @@ const useEditor = create<EditorState>()(
           set({ mode: 'select', tool: null, catalogCategory: null })
         }
 
+        // Leaving the site phase must drop a held sculpt scope: this branch
+        // rewrites `mode` without going through `setMode`, so without this a
+        // stuck `sculpting` scope would disable selection in structure phase.
+        syncBrushModeScope(get().mode)
+
         switch (phase) {
           case 'site':
             selectSiteFloorplanContext()
@@ -708,6 +979,23 @@ const useEditor = create<EditorState>()(
       },
       mode: DEFAULT_PERSISTED_EDITOR_UI_STATE.mode,
       setMode: (mode) => {
+        // Sculpting is a site-phase mode. Arming it from structure/furnish moves
+        // the phase rather than failing silently: the user asked for the ground,
+        // and `normalizeModeForPhase` would otherwise reject the mode on the next
+        // rehydrate, leaving the UI showing a mode the store does not hold.
+        if (mode === 'terrain-sculpt' && get().phase !== 'site') {
+          get().setPhase('site')
+        }
+
+        // Same promotion, one axis over. The brush needs the 3D canvas: in `2d`
+        // the pane is only `display: none`, so the mode would arm, hold its
+        // scope and show its HUD while no pointer event could ever reach it.
+        // `split` is the smallest move that satisfies it — a plain `3d` would
+        // throw away a floorplan the user deliberately opened.
+        if (mode === 'terrain-sculpt' && get().viewMode === '2d') {
+          set({ viewMode: 'split', isFloorplanOpen: true })
+        }
+
         set({ mode })
 
         const { phase, structureLayer, tool } = get()
@@ -730,6 +1018,15 @@ const useEditor = create<EditorState>()(
         else if (tool) {
           set({ tool: null })
         }
+
+        if (mode === 'terrain-sculpt') {
+          // Sculpting acts on the ground, never on a node. Clearing the
+          // selection on entry is what stops the selected wall's gizmo from
+          // sitting under the brush, competing for the same clicks.
+          useViewer.getState().setSelection({ selectedIds: [], zoneId: null })
+        }
+
+        syncBrushModeScope(mode)
       },
       tool: DEFAULT_PERSISTED_EDITOR_UI_STATE.tool,
       setTool: (tool) => set({ tool }),
@@ -744,6 +1041,8 @@ const useEditor = create<EditorState>()(
           }
           return { toolDefaults: next }
         }),
+      lastMeasurementKind: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.lastMeasurementKind,
+      setLastMeasurementKind: (kind) => set({ lastMeasurementKind: kind }),
       structureLayer: DEFAULT_PERSISTED_EDITOR_UI_STATE.structureLayer,
       setStructureLayer: (layer) => {
         const { mode } = get()
@@ -753,6 +1052,7 @@ const useEditor = create<EditorState>()(
           set({ structureLayer: layer, tool })
         } else {
           set({ structureLayer: layer, mode: 'select', tool: null })
+          syncBrushModeScope('select')
         }
 
         const viewer = useViewer.getState()
@@ -765,48 +1065,57 @@ const useEditor = create<EditorState>()(
       setCatalogCategory: (category) => set({ catalogCategory: category }),
       selectedItem: null,
       setSelectedItem: (item) => set({ selectedItem: item }),
-      movingNode: null as
-        | ItemNode
-        | WindowNode
-        | DoorNode
-        | ElevatorNode
-        | CeilingNode
-        | ColumnNode
-        | SlabNode
-        | WallNode
-        | FenceNode
-        | RoofNode
-        | RoofSegmentNode
-        | SpawnNode
-        | StairNode
-        | StairSegmentNode
-        | BuildingNode
-        | null,
       placementDragMode: false,
       setPlacementDragMode: (dragMode) => set({ placementDragMode: dragMode }),
-      setMovingNode: (node) =>
-        set(
-          node === null
-            ? // Preserve `movingNodeOrigin` across the clear so the
-              // non-owning side's effect cleanup — which fires after
-              // `setMovingNode(null)` propagates — can still read who
-              // finalised. The next non-null `setMovingNode` resets it.
-              // Always clear the press-drag flag when a move ends.
-              { movingNode: null, placementDragMode: false }
-            : { movingNode: node, movingNodeOrigin: null },
-        ),
+      roofHostDragArmedId: null,
+      setRoofHostDragArmedId: (nodeId) => set({ roofHostDragArmedId: nodeId }),
+      // The node being placed/moved now lives inside the interaction scope
+      // (`useMovingNode` / `getMovingNode`), not a `useEditor` flag. This setter
+      // remains the single entry point: it drives the scope and still touches
+      // `movingNodeOrigin` / `placementDragMode` so cross-store subscribers that
+      // watch this store (community placement) keep firing on move start/end.
+      setMovingNode: (node) => {
+        const scope = useInteractionScope.getState()
+        if (node === null) {
+          scope.endIf((s) => s.kind === 'placing' || s.kind === 'moving')
+          // Preserve `movingNodeOrigin` across the clear so the non-owning
+          // side's effect cleanup — which fires after `setMovingNode(null)`
+          // propagates — can still read who finalised. The next non-null
+          // `setMovingNode` resets it. Always clear the press-drag flag.
+          set({ placementDragMode: false })
+          return
+        }
+        const targetNode = resolveMovingNodeTarget(node)
+        const isNew = Boolean((targetNode as { metadata?: { isNew?: boolean } }).metadata?.isNew)
+        if (isNew) {
+          scope.begin({
+            kind: 'placing',
+            node: targetNode,
+            nodeId: targetNode.id,
+            nodeType: targetNode.type,
+            view: '3d',
+            pressDrag: get().placementDragMode,
+          })
+        } else {
+          scope.begin({
+            kind: 'moving',
+            node: targetNode,
+            nodeId: targetNode.id,
+            nodeType: targetNode.type,
+            view: '3d',
+          })
+        }
+        set({ movingNodeOrigin: null })
+      },
       movingNodeOrigin: null as '2d' | '3d' | null,
       setMovingNodeOrigin: (origin) => set({ movingNodeOrigin: origin }),
-      movingWallEndpoint: null,
-      setMovingWallEndpoint: (value) => set({ movingWallEndpoint: value }),
-      movingFenceEndpoint: null,
-      setMovingFenceEndpoint: (value) => set({ movingFenceEndpoint: value }),
-      activeHandleDrag: null,
-      setActiveHandleDrag: (drag) => set({ activeHandleDrag: drag }),
-      curvingWall: null,
-      setCurvingWall: (wall) => set({ curvingWall: wall }),
-      curvingFence: null,
-      setCurvingFence: (fence) => set({ curvingFence: fence }),
+      rotationAxis: 'y',
+      cycleRotationAxis: () => {
+        const order = ['y', 'x', 'z'] as const
+        const next = order[(order.indexOf(get().rotationAxis as 'y' | 'x' | 'z') + 1) % 3]!
+        set({ rotationAxis: next })
+        return next
+      },
       selectedMaterialTarget: null,
       setSelectedMaterialTarget: (target) => set({ selectedMaterialTarget: target }),
       activePaintMaterial: null,
@@ -819,6 +1128,19 @@ const useEditor = create<EditorState>()(
         set((state) =>
           state.activePaintTarget === target ? state : { activePaintTarget: target },
         ),
+      draftVertexCount: 0,
+      setDraftVertexCount: (count) =>
+        set((state) => (state.draftVertexCount === count ? state : { draftVertexCount: count })),
+      paintScope: 'single',
+      setPaintScope: (scope) => set({ paintScope: scope }),
+      cyclePaintScope: () => {
+        // Cycle within the hovered node's available scopes (what the click will
+        // actually hit). With nothing paintable hovered there's only `single`.
+        const scopes = get().paintHover?.scopes ?? (['single'] as PaintScope[])
+        const next = cyclePaintScopeValue(get().paintScope, scopes)
+        set({ paintScope: next })
+        return next
+      },
       paintEraser: false,
       setPaintEraser: (eraser) => set({ paintEraser: eraser }),
       primeMaterialPaintFromSelection: () => {
@@ -848,15 +1170,29 @@ const useEditor = create<EditorState>()(
           activePaintMaterial: activePaintMaterial ?? get().activePaintMaterial,
         }
       },
-      hoveredPaintTarget: null,
-      setHoveredPaintTarget: (target) =>
-        set((state) =>
-          state.hoveredPaintTarget === target ? state : { hoveredPaintTarget: target },
-        ),
-      isPaintPanelOpen: false,
-      setPaintPanelOpen: (open) => set({ isPaintPanelOpen: open }),
+      paintHover: null,
+      setPaintHover: (info) => set({ paintHover: info }),
+      terrainVerb: 'flatten',
+      setTerrainVerb: (verb) =>
+        set({
+          terrainVerb: verb,
+          // Switching away from flatten drops the sampling arm — an eyedropper
+          // that survives into the raise brush would swallow its first click.
+          terrainSampling: verb === 'flatten' ? get().terrainSampling : false,
+        }),
+      terrainBrush: DEFAULT_BRUSH_SETTINGS,
+      setTerrainBrush: (settings) => set({ terrainBrush: { ...get().terrainBrush, ...settings } }),
+      terrainFlattenTarget: null,
+      setTerrainFlattenTarget: (metres) =>
+        set({ terrainFlattenTarget: metres, terrainSampling: false }),
+      terrainSampling: false,
+      setTerrainSampling: (sampling) => set({ terrainSampling: sampling }),
+      canFindNode: false,
+      setCanFindNode: (canFind) => set({ canFindNode: canFind }),
       selectedReferenceId: null,
       setSelectedReferenceId: (id) => set({ selectedReferenceId: id }),
+      referenceScaleActiveGuideId: null,
+      setReferenceScaleActiveGuideId: (id) => set({ referenceScaleActiveGuideId: id }),
       guideUi: {},
       setGuideLocked: (guideId, locked) =>
         set((state) => ({
@@ -889,8 +1225,6 @@ const useEditor = create<EditorState>()(
         }),
       spaces: {},
       setSpaces: (spaces) => set({ spaces }),
-      editingHole: null,
-      setEditingHole: (hole) => set({ editingHole: hole }),
       hoveredHole: null,
       setHoveredHole: (hole) =>
         set((state) =>
@@ -903,6 +1237,7 @@ const useEditor = create<EditorState>()(
       setPreviewMode: (preview) => {
         if (preview) {
           set({ isPreviewMode: true, mode: 'select', tool: null, catalogCategory: null })
+          syncBrushModeScope('select')
           // Clear zone/item selection for clean viewer drill-down hierarchy
           useViewer.getState().setSelection({ selectedIds: [], zoneId: null })
         } else {
@@ -914,10 +1249,45 @@ const useEditor = create<EditorState>()(
       setCaptureMode: (next) => {
         const resolved: CaptureMode =
           typeof next === 'boolean' ? { mode: next ? 'standard' : 'idle' } : next
-        set({ captureMode: resolved, isCaptureMode: resolved.mode !== 'idle' })
+        const entering = resolved.mode !== 'idle'
+        set((state) => {
+          if (entering) {
+            // Force 3D for the shot. Remember the prior mode only on the first
+            // entry (viewMode is already '3d' on re-entry), so we restore the
+            // user's real choice — not the forced '3d' — when capture ends.
+            if (state.viewMode !== '3d') {
+              viewModeBeforeCapture = state.viewMode
+              return {
+                captureMode: resolved,
+                isCaptureMode: true,
+                viewMode: '3d',
+                isFloorplanOpen: false,
+              }
+            }
+            return { captureMode: resolved, isCaptureMode: true }
+          }
+          const restore = viewModeBeforeCapture
+          viewModeBeforeCapture = null
+          if (restore && restore !== '3d') {
+            return {
+              captureMode: resolved,
+              isCaptureMode: false,
+              viewMode: restore,
+              isFloorplanOpen: true,
+            }
+          }
+          return { captureMode: resolved, isCaptureMode: false }
+        })
       },
       viewMode: DEFAULT_PERSISTED_EDITOR_UI_STATE.viewMode,
-      setViewMode: (mode) => set({ viewMode: mode, isFloorplanOpen: mode !== '3d' }),
+      setViewMode: (mode) => {
+        set({ viewMode: mode, isFloorplanOpen: mode !== '3d' })
+        // Going the other way, the view wins and the mode yields. Hiding the 3D
+        // pane leaves the brush unreachable, and a held `sculpting` scope would
+        // then keep selection suppressed in a floorplan the user is trying to
+        // work in — a mode you cannot use and cannot see how to leave.
+        if (mode === '2d' && get().mode === 'terrain-sculpt') get().setMode('select')
+      },
       splitOrientation: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.splitOrientation,
       setSplitOrientation: (orientation) => set({ splitOrientation: orientation }),
       isFloorplanOpen: DEFAULT_PERSISTED_EDITOR_UI_STATE.isFloorplanOpen,
@@ -929,20 +1299,64 @@ const useEditor = create<EditorState>()(
         }),
       isFloorplanHovered: false,
       setFloorplanHovered: (hovered) => set({ isFloorplanHovered: hovered }),
+      isRiserOpen: false,
+      setRiserOpen: (open) => set({ isRiserOpen: open }),
+      toggleRiserOpen: () => set((state) => ({ isRiserOpen: !state.isRiserOpen })),
       navigationSyncPose: null,
-      publishNavigationSyncPose: (pose) =>
-        set((state) => ({
-          navigationSyncPose: {
-            ...pose,
-            revision: (state.navigationSyncPose?.revision ?? 0) + 1,
-          },
-        })),
+      publishNavigationSyncPose: (pose) => {
+        const navigationSyncPose = {
+          ...pose,
+          revision: (get().navigationSyncPose?.revision ?? 0) + 1,
+        }
+        publishNavigationSyncPoseToStore(navigationSyncPose)
+        set({ navigationSyncPose })
+      },
       floorplanSelectionTool: 'click' as FloorplanSelectionTool,
       setFloorplanSelectionTool: (tool) => set({ floorplanSelectionTool: tool }),
       gridSnapStep: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.gridSnapStep,
       setGridSnapStep: (step) => set({ gridSnapStep: step }),
+      cycleGridSnapStep: () => {
+        const current = get().gridSnapStep
+        const index = GRID_SNAP_STEPS.indexOf(current)
+        const next = GRID_SNAP_STEPS[(index + 1) % GRID_SNAP_STEPS.length] ?? GRID_SNAP_STEPS[0]!
+        set({ gridSnapStep: next })
+        return next
+      },
       magneticSnap: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.magneticSnap,
       setMagneticSnap: (enabled) => set({ magneticSnap: enabled }),
+      snappingModeByContext: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.snappingModeByContext,
+      setSnappingMode: (context, mode) =>
+        set((state) => ({
+          snappingModeByContext: { ...state.snappingModeByContext, [context]: mode },
+        })),
+      cycleSnappingMode: () => {
+        const context = getActiveSnapContext() ?? 'item'
+        const current = get().snappingModeByContext[context]
+        const next = cycleSnappingModeIn(context, current)
+        set((state) => ({
+          snappingModeByContext: { ...state.snappingModeByContext, [context]: next },
+        }))
+        return next
+      },
+      continuationByContext: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.continuationByContext,
+      setContinuation: (context, mode) => {
+        const next =
+          migrateContinuationMode(mode, context) ?? CONTINUATION_PROFILES[context].default
+        set((state) => ({
+          continuationByContext: { ...state.continuationByContext, [context]: next },
+        }))
+      },
+      cycleContinuation: (context) => {
+        const next = nextContinuation(context, get().getContinuation(context))
+        set((state) => ({
+          continuationByContext: { ...state.continuationByContext, [context]: next },
+        }))
+        return next
+      },
+      getContinuation: (context) => {
+        const current = get().continuationByContext[context]
+        return migrateContinuationMode(current, context) ?? CONTINUATION_PROFILES[context].default
+      },
       showReferenceFloor: DEFAULT_PERSISTED_EDITOR_LAYOUT_STATE.showReferenceFloor,
       toggleReferenceFloor: () =>
         set((state) => ({ showReferenceFloor: !state.showReferenceFloor })),
@@ -955,6 +1369,8 @@ const useEditor = create<EditorState>()(
         set({ referenceFloorOpacity: Math.min(0.8, Math.max(0.1, opacity)) }),
       allowUndergroundCamera: false,
       setAllowUndergroundCamera: (enabled) => set({ allowUndergroundCamera: enabled }),
+      show2dVoronoi: false,
+      setShow2dVoronoi: (enabled) => set({ show2dVoronoi: enabled }),
       isFirstPersonMode: false,
       _viewModeBeforeFirstPerson: null as ViewMode | null,
       setFirstPersonMode: (enabled) => {
@@ -969,6 +1385,7 @@ const useEditor = create<EditorState>()(
             tool: null,
             catalogCategory: null,
           })
+          syncBrushModeScope('select')
         } else {
           const prevMode = get()._viewModeBeforeFirstPerson
           set({
@@ -993,6 +1410,7 @@ const useEditor = create<EditorState>()(
             tool: null,
             catalogCategory: null,
           })
+          syncBrushModeScope('select')
           // Clear selection so no edit affordances bleed into the clean canvas.
           useViewer.getState().setSelection({ selectedIds: [], zoneId: null })
         } else {
@@ -1014,11 +1432,35 @@ const useEditor = create<EditorState>()(
     }),
     {
       name: 'pascal-editor-ui-preferences',
-      merge: (persistedState, currentState) => ({
-        ...currentState,
-        ...normalizePersistedEditorUiState(persistedState as Partial<PersistedEditorState>),
-        ...normalizePersistedEditorLayoutState(persistedState as Partial<PersistedEditorState>),
-      }),
+      merge: (persistedState, currentState) => {
+        const uiState = normalizePersistedEditorUiState(
+          persistedState as Partial<PersistedEditorState>,
+        )
+        const layoutState = normalizePersistedEditorLayoutState(
+          persistedState as Partial<PersistedEditorState>,
+        )
+
+        return {
+          ...currentState,
+          ...uiState,
+          ...layoutState,
+          ...(uiState.mode === 'build' && uiState.tool === 'measurement'
+            ? {
+                toolDefaults: {
+                  ...currentState.toolDefaults,
+                  measurement: { kind: layoutState.lastMeasurementKind },
+                },
+              }
+            : {}),
+        }
+      },
+      // `mode` is persisted, but the interaction scope a brush mode holds is not
+      // — it lives in a separate, non-persisted store. Rehydrating into
+      // `terrain-sculpt` (or paint) without re-claiming the scope would restore
+      // the brush with selection still enabled, so every dab could grab a wall.
+      onRehydrateStorage: () => (state) => {
+        if (state) syncBrushModeScope(state.mode)
+      },
       partialize: (state) => ({
         phase: state.phase,
         mode: state.mode,
@@ -1033,12 +1475,109 @@ const useEditor = create<EditorState>()(
         floorplanSelectionTool: state.floorplanSelectionTool,
         gridSnapStep: state.gridSnapStep,
         magneticSnap: state.magneticSnap,
+        lastMeasurementKind: state.lastMeasurementKind,
+        snappingModeByContext: state.snappingModeByContext,
+        continuationByContext: state.continuationByContext,
         showReferenceFloor: state.showReferenceFloor,
         referenceFloorOffset: state.referenceFloorOffset,
         referenceFloorOpacity: state.referenceFloorOpacity,
       }),
+      skipHydration: true,
     },
   ),
 )
 
+/**
+ * Effective magnetic-snap state: the legacy `magneticSnap` flag AND the active
+ * context's snapping mode. With exclusive modes, magnetic (alignment axes + wall
+ * corner-join) is on only in `'lines'`. Read from the smallest magnetic choke
+ * points so the mode is honoured without retuning any snap math.
+ */
+export function isMagneticSnapActive(): boolean {
+  const state = useEditor.getState()
+  return state.magneticSnap && resolveSnapFlags(getActiveSnappingMode()).magnetic
+}
+
+/**
+ * Effective angle-lock state: the active context's snapping mode. With exclusive
+ * modes the 15°/45° lock is on only in `'angles'`. Read from the smallest
+ * angle-lock choke points (wall / fence draft call sites).
+ */
+export function isAngleSnapActive(): boolean {
+  return resolveSnapFlags(getActiveSnappingMode()).angles
+}
+
+/**
+ * Effective grid-lattice state: the active context's snapping mode. With
+ * exclusive modes the grid quantize is on only in `'grid'`.
+ */
+export function isGridSnapActive(): boolean {
+  return resolveSnapFlags(getActiveSnappingMode()).grid
+}
+
+/**
+ * Whether alignment "lines" should be DISPLAYED for the active context.
+ *
+ * True whenever a snappable context is active — in EVERY snapping mode,
+ * including `'off'`. The guides are passive reference feedback; this is
+ * decoupled from the magnetic *pull*: a producer publishes guides whenever this
+ * is true, but only applies the alignment delta when `isMagneticSnapActive()`
+ * (i.e. `'lines'`). So the user always sees the same alignment lines while
+ * snapping to grid / angles / off, and only snaps to them in `'lines'` mode.
+ */
+export function isAlignmentGuideActive(): boolean {
+  return getActiveSnapContext() !== null
+}
+
+/**
+ * The snapping context for what the user is currently doing (wall / item /
+ * polygon), or null when nothing snappable is active. Derived from the
+ * authoritative interaction scope, falling back to the armed build tool (the
+ * `drafting` scope isn't wired). The single source every snap reader + the HUD
+ * resolve their mode through.
+ */
+export function getActiveSnapContext(): SnapContext | null {
+  const editor = useEditor.getState()
+  return snapContextOf({
+    scope: useInteractionScope.getState().scope,
+    mode: editor.mode,
+    tool: editor.tool,
+    profileOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapProfile,
+    profileOfNode: (nodeId) => {
+      const node = useScene.getState().nodes[nodeId as AnyNodeId]
+      return node ? nodeRegistry.get(node.type)?.snapProfile : undefined
+    },
+    draftDirectionalOf: (typeOrTool) => nodeRegistry.get(typeOrTool)?.snapDraftDirectional ?? true,
+  })
+}
+
+export function getActiveContinuationContext(): ContinuationContext | null {
+  const scope = useInteractionScope.getState().scope
+  if (scope.kind === 'drafting') return continuationContextOf(scope.tool)
+  if (scope.kind === 'placing') return continuationContextOf(scope.nodeType)
+  if (scope.kind !== 'idle') return null
+
+  const editor = useEditor.getState()
+  if (editor.mode !== 'build' || !editor.tool) return null
+  return continuationContextOf(editor.tool)
+}
+
+export function getContinuation(context: ContinuationContext): ContinuationMode {
+  return useEditor.getState().getContinuation(context)
+}
+
+/**
+ * The effective snapping mode for the active context. Falls back to `'off'` when
+ * no snappable context is active (select / idle, no armed tool) so grid /
+ * magnetic / angle readers — including the snap-grid overlay — stay inert
+ * outside an interaction. Per-context defaults (item is `'grid'`) only take
+ * effect once a tool is armed or an interaction begins; otherwise the item
+ * default would light up the snap grid at idle.
+ */
+export function getActiveSnappingMode(): SnappingMode {
+  const context = getActiveSnapContext()
+  if (!context) return 'off'
+  return useEditor.getState().snappingModeByContext[context]
+}
+
 export default useEditor