@pascal-app/editor 0.8.0 → 0.9.2

package/src/lib/snapping-mode.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  cycleSnappingModeIn,
+  DEFAULT_SNAPPING_MODE,
+  defaultSnappingModeFor,
+  nextSnappingMode,
+  resolveSnapFlags,
+  SNAPPING_MODES,
+  snapContextOf,
+  snappingModesFor,
+} from './snapping-mode'
+
+describe('resolveSnapFlags', () => {
+  it('default mode is grid', () => {
+    expect(DEFAULT_SNAPPING_MODE).toBe('grid')
+  })
+
+  it("modes are exclusive: 'grid' snaps to the lattice only", () => {
+    expect(resolveSnapFlags('grid')).toEqual({ grid: true, magnetic: false, angles: false })
+  })
+
+  it("'off' disables grid, magnetic, and angles", () => {
+    expect(resolveSnapFlags('off')).toEqual({ grid: false, magnetic: false, angles: false })
+  })
+
+  it("'lines' keeps magnetic but drops the grid lattice and angle lock", () => {
+    expect(resolveSnapFlags('lines')).toEqual({ grid: false, magnetic: true, angles: false })
+  })
+
+  it("'angles' keeps the angle lock but drops grid and magnetic", () => {
+    expect(resolveSnapFlags('angles')).toEqual({ grid: false, magnetic: false, angles: true })
+  })
+
+  it("'lines' and 'angles' are distinct", () => {
+    expect(resolveSnapFlags('lines')).not.toEqual(resolveSnapFlags('angles'))
+  })
+
+  it('cycles through every mode and wraps', () => {
+    const seen = [DEFAULT_SNAPPING_MODE]
+    let mode = DEFAULT_SNAPPING_MODE
+    for (let i = 0; i < SNAPPING_MODES.length - 1; i += 1) {
+      mode = nextSnappingMode(mode)
+      seen.push(mode)
+    }
+    expect(seen).toEqual(SNAPPING_MODES)
+    expect(nextSnappingMode(mode)).toBe(DEFAULT_SNAPPING_MODE)
+  })
+})
+
+describe('per-context snapping', () => {
+  it('items default to grid with no angle lock', () => {
+    expect(defaultSnappingModeFor('item')).toBe('grid')
+    expect(snappingModesFor('item')).toEqual(['lines', 'grid', 'off'])
+    expect(snappingModesFor('item')).not.toContain('angles')
+  })
+
+  it('walls default to grid and expose the angle lock; polygons do NOT', () => {
+    expect(defaultSnappingModeFor('wall')).toBe('grid')
+    expect(defaultSnappingModeFor('polygon')).toBe('grid')
+    expect(snappingModesFor('wall')).toContain('angles')
+    // Angle lock is wall/fence-only — slabs, curves and translates never get it.
+    expect(snappingModesFor('polygon')).not.toContain('angles')
+    expect(snappingModesFor('polygon')).toEqual(['grid', 'lines', 'off'])
+  })
+
+  it('cycles within the context set and clamps a foreign value', () => {
+    expect(cycleSnappingModeIn('item', 'lines')).toBe('grid')
+    expect(cycleSnappingModeIn('item', 'off')).toBe('lines')
+    // 'angles' isn't an item mode → restart at the first entry
+    expect(cycleSnappingModeIn('item', 'angles')).toBe('lines')
+  })
+})
+
+describe('snapContextOf (profile-driven, node-declared)', () => {
+  // Stands in for the registry's declared `def.snapProfile` (the only per-kind
+  // data) — the resolver itself has no kind switch.
+  const declared: Record<string, 'item' | 'structural'> = {
+    wall: 'structural',
+    fence: 'structural',
+    item: 'item',
+    slab: 'structural',
+    ceiling: 'structural',
+    roof: 'structural',
+    zone: 'structural',
+  }
+  const profileOf = (t: string) => declared[t]
+  const ctx = (
+    scope: { kind: string; nodeType?: string; reshape?: string; tool?: string },
+    mode = 'select',
+    tool: string | null = null,
+  ) => snapContextOf({ scope, mode, tool, profileOf })
+
+  it('translating a whole structural node has no angle (polygon, not wall)', () => {
+    expect(ctx({ kind: 'moving', nodeType: 'wall' })).toBe('polygon')
+    expect(ctx({ kind: 'moving', nodeType: 'slab' })).toBe('polygon')
+    expect(ctx({ kind: 'placing', nodeType: 'item' }, 'build', 'item')).toBe('item')
+  })
+
+  it('endpoint reshape is angle-bearing (wall); curve + polygon vertex edits are not', () => {
+    expect(ctx({ kind: 'reshaping', reshape: 'endpoint' })).toBe('wall')
+    expect(ctx({ kind: 'reshaping', reshape: 'curve' })).toBe('polygon')
+    expect(ctx({ kind: 'reshaping', reshape: 'boundary' })).toBe('polygon')
+    expect(ctx({ kind: 'reshaping', reshape: 'hole' })).toBe('polygon')
+  })
+
+  it('drafting a structural kind (wall OR slab) is angle-bearing (wall)', () => {
+    expect(ctx({ kind: 'idle' }, 'build', 'wall')).toBe('wall')
+    expect(ctx({ kind: 'idle' }, 'build', 'slab')).toBe('wall')
+    expect(ctx({ kind: 'idle' }, 'build', 'item')).toBe('item')
+    expect(ctx({ kind: 'idle' }, 'select', null)).toBeNull()
+  })
+
+  it('an undeclared kind (no snapProfile) gets no snap context', () => {
+    expect(ctx({ kind: 'moving', nodeType: 'door' })).toBeNull()
+    expect(ctx({ kind: 'idle' }, 'build', 'shelf')).toBeNull()
+  })
+
+  it('drafting a non-directional structural kind is angle-less (polygon, not wall)', () => {
+    // Roof / stair / elevator are placed as footprints, not directional draws →
+    // declared `snapDraftDirectional: false`, so their draft context drops the
+    // angle-lock mode. Directional structural kinds (no flag) stay `wall`.
+    const draftDirectionalOf = (t: string) => t !== 'roof'
+    const draftCtx = (tool: string) =>
+      snapContextOf({ scope: { kind: 'idle' }, mode: 'build', tool, profileOf, draftDirectionalOf })
+    expect(draftCtx('roof')).toBe('polygon')
+    expect(draftCtx('wall')).toBe('wall')
+    // Also via the explicit `drafting` scope path.
+    expect(
+      snapContextOf({
+        scope: { kind: 'drafting', tool: 'roof' },
+        mode: 'build',
+        tool: 'roof',
+        profileOf,
+        draftDirectionalOf,
+      }),
+    ).toBe('polygon')
+  })
+})

package/src/lib/snapping-mode.ts

@@ -0,0 +1,179 @@
+import type { SnapProfile } from '@pascal-app/core'
+import { GROUP_MOVE_DRAG_LABEL } from './contextual-help'
+
+/**
+ * Snapping mode is a single global, user-cyclable control that maps onto the
+ * two pre-existing snap knobs (`gridSnapStep` grid snap + `magneticSnap`).
+ * The default `'grid'` resolves to the exact pair the editor shipped with
+ * before this control existed (grid on, magnetic on), so the default path is
+ * behaviourally unchanged — only when a user opts into `'lines'` or `'off'`
+ * does any snap math get suppressed.
+ */
+export type SnappingMode = 'grid' | 'lines' | 'angles' | 'off'
+
+export const SNAPPING_MODES: SnappingMode[] = ['grid', 'lines', 'angles', 'off']
+
+export const DEFAULT_SNAPPING_MODE: SnappingMode = 'grid'
+
+export type SnapFlags = {
+  grid: boolean
+  magnetic: boolean
+  angles: boolean
+}
+
+/**
+ * Pure mapping from the mode enum onto the individual snap knobs. Modes are
+ * EXCLUSIVE — each does exactly what its chip label says, one guide at a time,
+ * so the HUD is honest:
+ *
+ * - `grid`   → grid lattice only.
+ * - `lines`  → magnetic only: alignment axes + wall corner-join (connectivity
+ *   is part of the "lines" magnetic snap, not a separate always-on behaviour).
+ * - `angles` → angle lock only (15°/45° rays).
+ * - `off`    → nothing snaps (raw cursor).
+ */
+export function resolveSnapFlags(mode: SnappingMode): SnapFlags {
+  switch (mode) {
+    case 'grid':
+      return { grid: true, magnetic: false, angles: false }
+    case 'lines':
+      return { grid: false, magnetic: true, angles: false }
+    case 'angles':
+      return { grid: false, magnetic: false, angles: true }
+    case 'off':
+      return { grid: false, magnetic: false, angles: false }
+  }
+}
+
+const SNAPPING_MODE_LABELS: Record<SnappingMode, string> = {
+  grid: 'Grid',
+  lines: 'Lines',
+  angles: 'Angles',
+  off: 'Off',
+}
+
+export function getSnappingModeLabel(mode: SnappingMode): string {
+  return SNAPPING_MODE_LABELS[mode]
+}
+
+export function nextSnappingMode(mode: SnappingMode): SnappingMode {
+  const index = SNAPPING_MODES.indexOf(mode)
+  return SNAPPING_MODES[(index + 1) % SNAPPING_MODES.length] ?? DEFAULT_SNAPPING_MODE
+}
+
+// ── Per-context snapping ──────────────────────────────────────────────────────
+//
+// Snapping is no longer one global value: each *activity* has its own mode set
+// and default, because they want different behaviour (drawing a wall wants a
+// grid + angle lock; nudging an item wants free movement that only catches on
+// alignment lines). The mode is remembered per context and shown live, so it's
+// never a silent surprise — it just matches what you're doing.
+
+export type SnapContext = 'wall' | 'item' | 'polygon'
+
+// The cyclable mode-set for a context (distinct from the node's `SnapProfile`).
+type SnapModeSet = { modes: SnappingMode[]; default: SnappingMode }
+
+// `modes[0]` is the cycle's first entry; `default` is what a context starts at.
+// The 'wall' set is the ONLY one with an angle lock — it applies solely when
+// you're setting a segment's DIRECTION (wall/fence drafting + endpoint drag).
+// Translating a whole wall, curving it, or drawing/moving a slab can't change an
+// angle, so those use the no-angle 'polygon' set.
+const SNAP_PROFILES: Record<SnapContext, SnapModeSet> = {
+  // Wall / fence drafting + endpoint reshape: direction matters → angle lock.
+  wall: { modes: ['grid', 'lines', 'angles', 'off'], default: 'grid' },
+  // Item placement / move: grid by default; lines = magnetic alignment only (no
+  // grid lattice), no angle lock (meaningless for a footprint).
+  item: { modes: ['lines', 'grid', 'off'], default: 'grid' },
+  // Structural / surface, no direction to set: slab / ceiling / roof draft+move,
+  // whole wall/fence translate, curve reshape, polygon boundary edit. Grid by
+  // default, NO angle lock.
+  polygon: { modes: ['grid', 'lines', 'off'], default: 'grid' },
+}
+
+export const SNAP_CONTEXTS: SnapContext[] = ['wall', 'item', 'polygon']
+
+export function snappingModesFor(context: SnapContext): SnappingMode[] {
+  return SNAP_PROFILES[context].modes
+}
+
+export function defaultSnappingModeFor(context: SnapContext): SnappingMode {
+  return SNAP_PROFILES[context].default
+}
+
+// Cycle within the context's own set (clamps a foreign value to the first entry).
+export function cycleSnappingModeIn(context: SnapContext, mode: SnappingMode): SnappingMode {
+  const modes = SNAP_PROFILES[context].modes
+  const index = modes.indexOf(mode)
+  return modes[(index + 1) % modes.length] ?? modes[0] ?? DEFAULT_SNAPPING_MODE
+}
+
+// The kind's declared `snapProfile` (from the registry) → the active mode-set
+// context. The only behaviour difference is the angle lock, which a `structural`
+// kind gets while SETTING DIRECTION (drafting a run/polygon, dragging an endpoint
+// or a polygon vertex) — never while translating or curving. A node with no
+// declared profile has no snapping UI (chip) yet — returns null.
+function contextForProfile(
+  profile: SnapProfile | undefined,
+  directionSetting: boolean,
+): SnapContext | null {
+  if (profile === 'item') return 'item'
+  if (profile === 'structural') return directionSetting ? 'wall' : 'polygon'
+  return null
+}
+
+/**
+ * The active snapping context, derived from what the user is doing — fully
+ * node-declared: the kind's `snapProfile` (looked up via the injected
+ * `profileOf`) supplies the data, and this maps (profile × action) to the
+ * mode-set. No per-kind switch lives here. `profileOf` is injected so this stays
+ * pure + testable and `snapping-mode` need not import the registry.
+ *
+ * Prefers the authoritative interaction scope; falls back to the build tool
+ * because the `drafting` scope isn't wired yet (wall/slab draw runs idle).
+ * Returns null when nothing snappable is active → no chip, safe-default snap.
+ */
+export function snapContextOf(args: {
+  scope: {
+    kind: string
+    nodeType?: string
+    reshape?: string
+    nodeId?: string
+    tool?: string
+    handle?: string
+  }
+  mode: string
+  tool: string | null
+  profileOf: (typeOrTool: string) => SnapProfile | undefined
+  // Whether drafting a kind sets a direction (angle-lock meaningful). Injected
+  // like `profileOf` so `snapping-mode` need not import the registry; defaults
+  // to `true` (the structural draw default) when not supplied.
+  draftDirectionalOf?: (typeOrTool: string) => boolean
+}): SnapContext | null {
+  const { scope, mode, tool, profileOf, draftDirectionalOf } = args
+  // The group-move gizmo translates the whole selection — same no-angle
+  // treatment as a single-node move, so Shift cycles the 'item' modes and the
+  // HUD shows the item snapping chips for the drag.
+  if (scope.kind === 'handle-drag' && scope.handle === GROUP_MOVE_DRAG_LABEL) {
+    return 'item'
+  }
+  switch (scope.kind) {
+    case 'placing':
+    case 'moving':
+      // A whole-node translate never sets direction → no angle.
+      return scope.nodeType ? contextForProfile(profileOf(scope.nodeType), false) : null
+    case 'reshaping':
+      // Dragging a wall ENDPOINT sets the segment's direction → angle-bearing
+      // 'wall'. Curving, and polygon vertex/edge edits (boundary / hole), don't
+      // — they use the no-angle 'polygon' set (grid / lines / off).
+      return scope.reshape === 'endpoint' ? 'wall' : 'polygon'
+    case 'drafting':
+      return scope.tool
+        ? contextForProfile(profileOf(scope.tool), draftDirectionalOf?.(scope.tool) ?? true)
+        : null
+    default:
+      return mode === 'build' && tool
+        ? contextForProfile(profileOf(tool), draftDirectionalOf?.(tool) ?? true)
+        : null
+  }
+}

package/src/lib/stair-duplication.ts

@@ -37,7 +37,7 @@ function stripDuplicateFlags(metadata: unknown) {
 
 function moveStairWhenRegistered(stairId: StairNode['id'], attempt = 0) {
   const latestStair = useScene.getState().nodes[stairId as AnyNodeId]
-  if (!latestStair || latestStair.type !== 'stair') {
+  if (latestStair?.type !== 'stair') {
     return
   }
 
@@ -64,7 +64,7 @@ export function duplicateStairSubtree(
   const scene = useScene.getState()
   const sourceStair = scene.nodes[sourceStairId]
 
-  if (!sourceStair || sourceStair.type !== 'stair') {
+  if (sourceStair?.type !== 'stair') {
     throw new Error(`Node "${sourceStairId}" is not a stair`)
   }
 
@@ -89,7 +89,7 @@ export function duplicateStairSubtree(
   const segmentClones: StairSegmentNode[] = []
   for (const childId of sourceStair.children ?? []) {
     const childNode = scene.nodes[childId as AnyNodeId]
-    if (!childNode || childNode.type !== 'stair-segment') {
+    if (childNode?.type !== 'stair-segment') {
       continue
     }
 
@@ -108,7 +108,7 @@ export function duplicateStairSubtree(
   ])
 
   const createdStair = useScene.getState().nodes[stairClone.id as AnyNodeId]
-  if (!createdStair || createdStair.type !== 'stair') {
+  if (createdStair?.type !== 'stair') {
     throw new Error(`Duplicated stair "${stairClone.id}" was not created`)
   }
 

package/src/lib/stair-levels.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  BuildingNode,
+  LevelNode,
+  StairNode,
+} from '@pascal-app/core/schema'
+import {
+  getBuildingLevelsForLevel,
+  getStairLevelOptions,
+  resolveStairDestinationLevel,
+  resolveStairFromLevelId,
+  resolveStairPlacementLevelId,
+  resolveStairToLevelId,
+} from './stair-levels'
+
+describe('stair level helpers', () => {
+  test('creates a missing upper level in the same building', () => {
+    const ground = LevelNode.parse({ level: 0, children: [] })
+    const building = BuildingNode.parse({ children: [ground.id] })
+    const nodes = {
+      [building.id]: building,
+      [ground.id]: ground,
+    } as Record<AnyNodeId, AnyNode>
+
+    const plan = resolveStairDestinationLevel({
+      createMissing: true,
+      fromLevelId: ground.id,
+      nodes,
+    })
+
+    expect(plan?.buildingId).toBe(building.id)
+    expect(plan?.fromLevel.id).toBe(ground.id)
+    expect(plan?.toLevel.level).toBe(1)
+    expect(plan?.toLevel.id).toBe(plan?.createdLevel?.id)
+    expect(plan?.createdLevel?.parentId).toBe(building.id)
+  })
+
+  test('uses the nearest higher sibling level instead of creating one', () => {
+    const building = BuildingNode.parse({})
+    const ground = LevelNode.parse({ level: 0, parentId: building.id })
+    const second = LevelNode.parse({ level: 1, parentId: building.id })
+    const third = LevelNode.parse({ level: 2, parentId: building.id })
+    const nodes = {
+      [building.id]: { ...building, children: [ground.id, third.id, second.id] },
+      [ground.id]: ground,
+      [second.id]: second,
+      [third.id]: third,
+    } as Record<AnyNodeId, AnyNode>
+
+    const plan = resolveStairDestinationLevel({
+      createMissing: true,
+      fromLevelId: ground.id,
+      nodes,
+    })
+
+    expect(plan?.createdLevel).toBeNull()
+    expect(plan?.toLevel.id).toBe(second.id)
+  })
+
+  test('ignores levels from other buildings', () => {
+    const buildingA = BuildingNode.parse({})
+    const buildingB = BuildingNode.parse({})
+    const groundA = LevelNode.parse({ level: 0, parentId: buildingA.id })
+    const upperA = LevelNode.parse({ level: 1, parentId: buildingA.id })
+    const upperB = LevelNode.parse({ level: 1, parentId: buildingB.id })
+    const nodes = {
+      [buildingA.id]: { ...buildingA, children: [groundA.id, upperA.id] },
+      [buildingB.id]: { ...buildingB, children: [upperB.id] },
+      [groundA.id]: groundA,
+      [upperA.id]: upperA,
+      [upperB.id]: upperB,
+    } as Record<AnyNodeId, AnyNode>
+
+    expect(getBuildingLevelsForLevel(nodes, groundA.id).map((level) => level.id)).toEqual([
+      groundA.id,
+      upperA.id,
+    ])
+    expect(
+      resolveStairDestinationLevel({ createMissing: true, fromLevelId: groundA.id, nodes })?.toLevel
+        .id,
+    ).toBe(upperA.id)
+  })
+
+  test('includes source and parent-linked sibling levels when building children are stale', () => {
+    const building = BuildingNode.parse({ children: [] })
+    const ground = LevelNode.parse({ level: 0, parentId: building.id })
+    const upper = LevelNode.parse({ level: 1, parentId: building.id })
+    const nodes = {
+      [building.id]: building,
+      [ground.id]: ground,
+      [upper.id]: upper,
+    } as Record<AnyNodeId, AnyNode>
+
+    const levels = getBuildingLevelsForLevel(nodes, ground.id)
+    const plan = resolveStairDestinationLevel({
+      createMissing: true,
+      fromLevelId: ground.id,
+      nodes,
+    })
+
+    expect(levels.map((level) => level.id)).toEqual([ground.id, upper.id])
+    expect(plan?.createdLevel).toBeNull()
+    expect(plan?.toLevel.id).toBe(upper.id)
+  })
+
+  test('falls back from stale placement level ids to a valid level in the selected building', () => {
+    const buildingA = BuildingNode.parse({})
+    const groundA = LevelNode.parse({ level: 0, parentId: buildingA.id })
+    const buildingB = BuildingNode.parse({})
+    const groundB = LevelNode.parse({ level: 0, parentId: buildingB.id })
+    const nodes = {
+      [buildingA.id]: { ...buildingA, children: [groundA.id] },
+      [groundA.id]: groundA,
+      [buildingB.id]: { ...buildingB, children: [groundB.id] },
+      [groundB.id]: groundB,
+    } as Record<AnyNodeId, AnyNode>
+
+    expect(resolveStairPlacementLevelId(nodes, 'level_missing', buildingB.id)).toBe(groundB.id)
+  })
+
+  test('repairs panel level ids for stairs with stale from-level data', () => {
+    const building = BuildingNode.parse({})
+    const ground = LevelNode.parse({ level: 0, parentId: building.id })
+    const upper = LevelNode.parse({ level: 1, parentId: building.id })
+    const stair = StairNode.parse({
+      parentId: ground.id,
+      fromLevelId: 'default',
+      toLevelId: upper.id,
+    })
+    const nodes = {
+      [building.id]: { ...building, children: [ground.id, upper.id] },
+      [ground.id]: ground,
+      [upper.id]: upper,
+      [stair.id]: stair,
+    } as Record<AnyNodeId, AnyNode>
+
+    const levels = getStairLevelOptions(nodes, stair)
+    const fromLevelId = resolveStairFromLevelId(nodes, stair, levels)
+
+    expect(levels.map((level) => level.id)).toEqual([ground.id, upper.id])
+    expect(fromLevelId).toBe(ground.id)
+    expect(resolveStairToLevelId(nodes, stair, fromLevelId, levels)).toBe(upper.id)
+  })
+})

package/src/lib/stair-levels.ts

@@ -0,0 +1,177 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  LevelNode,
+  type LevelNode as LevelNodeType,
+  resolveBuildingForLevel,
+  type StairNode,
+} from '@pascal-app/core'
+
+function sortLevelsByHeight(levels: LevelNodeType[]) {
+  return [...levels].sort((left, right) => left.level - right.level)
+}
+
+function isLevelNode(node: AnyNode | undefined): node is LevelNodeType {
+  return node?.type === 'level'
+}
+
+function getAllSceneLevels(nodes: Record<string, AnyNode>) {
+  return sortLevelsByHeight(
+    Object.values(nodes).filter((entry): entry is LevelNodeType => entry?.type === 'level'),
+  )
+}
+
+function getBuildingLevels(
+  nodes: Record<string, AnyNode>,
+  buildingId: AnyNodeId | string | null | undefined,
+  source?: LevelNodeType,
+) {
+  if (!buildingId) return source ? [source] : []
+  const building = nodes[buildingId as AnyNodeId]
+  if (building?.type !== 'building') return source ? [source] : []
+
+  const levels = new Map<string, LevelNodeType>()
+  if (source) levels.set(source.id, source)
+
+  for (const childId of building.children ?? []) {
+    const child = nodes[childId as AnyNodeId]
+    if (isLevelNode(child)) levels.set(child.id, child)
+  }
+
+  for (const candidate of Object.values(nodes)) {
+    if (isLevelNode(candidate) && candidate.parentId === building.id) {
+      levels.set(candidate.id, candidate)
+    }
+  }
+
+  return sortLevelsByHeight(Array.from(levels.values()))
+}
+
+export function getBuildingLevelsForLevel(
+  nodes: Record<string, AnyNode>,
+  levelId: AnyNodeId | string | null | undefined,
+) {
+  if (!levelId) return []
+  const source = nodes[levelId as AnyNodeId]
+  if (!isLevelNode(source)) return []
+
+  const buildingId = resolveBuildingForLevel(
+    source.id as AnyNodeId,
+    nodes as Record<AnyNodeId, AnyNode>,
+  )
+  return getBuildingLevels(nodes, buildingId, source)
+}
+
+export function getStairLevelOptions(nodes: Record<string, AnyNode>, stair: StairNode) {
+  for (const candidateId of [stair.fromLevelId, stair.parentId, stair.toLevelId]) {
+    if (isLevelNode(nodes[candidateId as AnyNodeId])) {
+      return getBuildingLevelsForLevel(nodes, candidateId)
+    }
+  }
+
+  return getAllSceneLevels(nodes)
+}
+
+export function resolveStairPlacementLevelId(
+  nodes: Record<string, AnyNode>,
+  preferredLevelId: AnyNodeId | string | null | undefined,
+  preferredBuildingId?: AnyNodeId | string | null,
+) {
+  if (isLevelNode(nodes[preferredLevelId as AnyNodeId])) {
+    return preferredLevelId as LevelNodeType['id']
+  }
+
+  const buildingLevels = getBuildingLevels(nodes, preferredBuildingId)
+  return buildingLevels[0]?.id ?? getAllSceneLevels(nodes)[0]?.id ?? null
+}
+
+export function resolveStairFromLevelId(
+  nodes: Record<string, AnyNode>,
+  stair: StairNode,
+  levels = getStairLevelOptions(nodes, stair),
+) {
+  const optionIds = new Set<string>(levels.map((level) => level.id))
+  if (stair.fromLevelId && optionIds.has(stair.fromLevelId)) return stair.fromLevelId
+  if (stair.parentId && optionIds.has(stair.parentId)) return stair.parentId
+
+  const toLevel = stair.toLevelId ? nodes[stair.toLevelId as AnyNodeId] : undefined
+  if (isLevelNode(toLevel)) {
+    const lowerLevel = [...levels].reverse().find((level) => level.level < toLevel.level)
+    if (lowerLevel) return lowerLevel.id
+  }
+
+  return levels[0]?.id ?? null
+}
+
+export function resolveStairToLevelId(
+  nodes: Record<string, AnyNode>,
+  stair: StairNode,
+  fromLevelId: AnyNodeId | string | null | undefined,
+  levels = getStairLevelOptions(nodes, stair),
+) {
+  const optionIds = new Set<string>(levels.map((level) => level.id))
+  if (stair.toLevelId && stair.toLevelId !== fromLevelId && optionIds.has(stair.toLevelId)) {
+    return stair.toLevelId
+  }
+
+  const fromLevel = fromLevelId ? nodes[fromLevelId as AnyNodeId] : undefined
+  if (isLevelNode(fromLevel)) {
+    return levels.find((level) => level.level > fromLevel.level)?.id ?? fromLevel.id
+  }
+
+  return levels[0]?.id ?? null
+}
+
+export function resolveStairDestinationLevel({
+  createMissing,
+  fromLevelId,
+  nodes,
+}: {
+  createMissing?: boolean
+  fromLevelId: AnyNodeId | string | null | undefined
+  nodes: Record<string, AnyNode>
+}) {
+  if (!fromLevelId) return null
+  const fromLevel = nodes[fromLevelId as AnyNodeId]
+  if (!isLevelNode(fromLevel)) return null
+
+  const buildingId = resolveBuildingForLevel(
+    fromLevel.id as AnyNodeId,
+    nodes as Record<AnyNodeId, AnyNode>,
+  )
+  const levels = getBuildingLevelsForLevel(nodes, fromLevel.id)
+  const nextExistingLevel = levels.find((level) => level.level > fromLevel.level) ?? null
+  if (nextExistingLevel) {
+    return {
+      buildingId,
+      createdLevel: null,
+      fromLevel,
+      levels,
+      toLevel: nextExistingLevel,
+    }
+  }
+
+  if (createMissing && buildingId) {
+    const createdLevel = LevelNode.parse({
+      children: [],
+      level: fromLevel.level + 1,
+      parentId: buildingId,
+    })
+
+    return {
+      buildingId,
+      createdLevel,
+      fromLevel,
+      levels: sortLevelsByHeight([...levels, createdLevel]),
+      toLevel: createdLevel,
+    }
+  }
+
+  return {
+    buildingId,
+    createdLevel: null,
+    fromLevel,
+    levels,
+    toLevel: fromLevel,
+  }
+}