@pascal-app/editor 1.0.3 → 1.0.4

package/src/lib/mezzanine-draft.ts

@@ -0,0 +1,278 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  area,
+  containsPoint,
+  createMezzanine,
+  generateId,
+  getStoredLevelHeight,
+  type LevelNode,
+  type MultiPolygon,
+  type StructurePlan,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { create } from 'zustand'
+import { getRoomSelectionIndex } from '../hooks/use-selected-room'
+import useEditor from '../store/use-editor'
+import {
+  CROSSING_MESSAGE,
+  clipFloorRegion,
+  floorRegionAxisAngle,
+  floorRegionSelfIntersects,
+} from './floor-region-geometry'
+import {
+  cancelFloorRegion,
+  type FloorDraftCommit,
+  type FloorDraftPurpose,
+  type FloorRegionRoom,
+  useFloorRegionDraft,
+} from './floor-region-session'
+import { type FloorRegionPoint, floorRegionSnapTargets } from './floor-region-snap'
+import { beginGesture, type GestureHandle } from './gesture-lifecycle'
+import {
+  MEZZANINE_FAILED_MESSAGE,
+  MEZZANINE_OUTSIDE_MESSAGE,
+  MEZZANINE_TOO_SMALL_MESSAGE,
+  mezzanineConflictMessage,
+} from './mezzanine-messages'
+import { applyRoomPlan } from './room-structure-commands'
+import { sfxEmitter } from './sfx-bus'
+
+// "Add mezzanine": draws a mezzanine outline inside one room with the floor
+// region draft (rectangle or polygon), snapped to the room's walls, and builds
+// it with core's `createMezzanine` at the default half-storey elevation (one
+// undo step). The tool is one lifecycle gesture from `startMezzanineDraft`
+// until the mezzanine is built or the tool is cancelled (Escape, a mode,
+// level or selection change, the room gone); refused outlines stay red with a
+// short label and the tool stays armed for another try.
+
+export const MEZZANINE_DRAFT_HANDLE = 'mezzanine-draft'
+
+export type MezzanineShape = 'rectangle' | 'polygon'
+
+export const useMezzanineDraft = create<{
+  /** The room the mezzanine is drawn in while the tool is armed. */
+  host: FloorRegionRoom | null
+  shape: MezzanineShape
+}>(() => ({ host: null, shape: 'rectangle' }))
+
+/** The mezzanine's default elevation: half the storey, as `createMezzanine` rounds it. */
+export function defaultMezzanineElevation(level: LevelNode) {
+  return Math.round(getStoredLevelHeight(level) * 10) / 20
+}
+
+const ON_BOUNDARY = 1e-4
+
+function distanceToSegment(p: FloorRegionPoint, a: FloorRegionPoint, b: FloorRegionPoint) {
+  const dx = b[0] - a[0]
+  const dz = b[1] - a[1]
+  const lengthSq = dx * dx + dz * dz
+  const t = lengthSq
+    ? Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dz) / lengthSq))
+    : 0
+  return Math.hypot(a[0] + t * dx - p[0], a[1] + t * dz - p[1])
+}
+
+/** Inside the polygon, or on its boundary (a point snapped onto a wall line). */
+function insideOrOn(polygon: MultiPolygon, point: FloorRegionPoint) {
+  if (containsPoint(polygon, point)) return true
+  return polygon.some(({ outer, holes }) =>
+    [outer, ...holes].some((ring) =>
+      ring.some((a, i) => distanceToSegment(point, a, ring[(i + 1) % ring.length]!) <= ON_BOUNDARY),
+    ),
+  )
+}
+
+function withoutRepeats(ring: FloorRegionPoint[]) {
+  return ring.filter((point, i) => {
+    const next = ring[(i + 1) % ring.length]!
+    return Math.hypot(next[0] - point[0], next[1] - point[1]) > ON_BOUNDARY
+  })
+}
+
+function refuse(message: string): FloorDraftCommit {
+  return { ok: false, message }
+}
+
+/**
+ * Why a mezzanine outline cannot be built, or its plan. The outline is clipped
+ * to the host's clear floor (inside the wall faces) first; what the clip
+ * leaves must be one piece of at least 1 m².
+ */
+export function planMezzanine(
+  nodes: Record<string, AnyNode>,
+  host: FloorRegionRoom,
+  polygon: readonly FloorRegionPoint[],
+): { plan: StructurePlan & { zoneId: string } } | { message: string } {
+  const clip = clipFloorRegion(polygon, host.clear)
+  if (!clip)
+    return {
+      message:
+        area([{ outer: polygon.map(([x, z]) => [x, z]), holes: [] }]) < 1
+          ? MEZZANINE_TOO_SMALL_MESSAGE
+          : MEZZANINE_OUTSIDE_MESSAGE,
+    }
+  if (clip.pieces.length !== 1) return { message: MEZZANINE_OUTSIDE_MESSAGE }
+  if (clip.area < 1) return { message: MEZZANINE_TOO_SMALL_MESSAGE }
+  const outline = withoutRepeats(clip.polygon)
+  let plan: StructurePlan & { zoneId: string }
+  try {
+    // The height the preview was drawn at, not one recomputed from a storey
+    // that may have changed while the tool was armed.
+    plan = createMezzanine(nodes, {
+      hostZoneId: host.zoneId,
+      polygon: outline,
+      elevation: host.elevation,
+      mintId: generateId,
+    })
+  } catch {
+    return {
+      message: floorRegionSelfIntersects(outline)
+        ? CROSSING_MESSAGE
+        : area([{ outer: outline, holes: [] }]) < 1
+          ? MEZZANINE_TOO_SMALL_MESSAGE
+          : MEZZANINE_FAILED_MESSAGE,
+    }
+  }
+  const conflict = plan.conflicts?.[0]
+  if (!conflict) return { plan }
+  return { message: mezzanineConflictMessage(conflict.code) ?? MEZZANINE_FAILED_MESSAGE }
+}
+
+// The tool's lifecycle handle, from start until built or cancelled.
+let tool: GestureHandle | null = null
+
+function reset() {
+  if (useMezzanineDraft.getState().host) useMezzanineDraft.setState({ host: null })
+  const { draft } = useFloorRegionDraft.getState()
+  if (draft?.room.purpose === MEZZANINE) useFloorRegionDraft.setState({ draft: null, hover: null })
+}
+
+function commitMezzanine(host: FloorRegionRoom, polygon: readonly FloorRegionPoint[]) {
+  const result = planMezzanine(useScene.getState().nodes, host, polygon)
+  if ('message' in result) return refuse(result.message)
+  const handle = tool
+  tool = null
+  try {
+    if (handle?.active) handle.finish(() => applyRoomPlan(result.plan))
+    else applyRoomPlan(result.plan)
+  } finally {
+    reset()
+  }
+  sfxEmitter.emit('sfx:structure-build')
+  useEditor.getState().selectRoom({ levelId: host.levelId, zoneId: result.plan.zoneId })
+  return { ok: true } as const
+}
+
+function hostGone(host: FloorRegionRoom) {
+  const scene = useScene.getState()
+  const zone = scene.nodes[host.zoneId as AnyNodeId]
+  return (
+    scene.readOnly ||
+    zone?.type !== 'zone' ||
+    zone.parentId !== host.levelId ||
+    useEditor.getState().room?.zoneId !== host.zoneId
+  )
+}
+
+function beginTool(host: FloorRegionRoom) {
+  const handle = beginGesture({
+    kind: 'mezzanine-draft',
+    scope: { kind: 'handle-drag', nodeId: host.zoneId, handle: MEZZANINE_DRAFT_HANDLE },
+    stale: () => hostGone(host),
+    onCancel: () => {
+      if (tool === handle) tool = null
+      reset()
+    },
+  })
+  tool = handle
+  useMezzanineDraft.setState({ host })
+  return handle
+}
+
+const MEZZANINE: FloorDraftPurpose = {
+  persistent: true,
+  own: (room) => (tool?.active ? tool : beginTool(room)),
+  commit: commitMezzanine,
+  pointMessage: (room, point) => (insideOrOn(room.clear, point) ? null : MEZZANINE_OUTSIDE_MESSAGE),
+  fill: '#818cf8',
+}
+
+/**
+ * The room a mezzanine is drawn in: its clear floor (inside the wall faces,
+ * which is what core accepts) bounds the outline, which snaps to those faces
+ * and the level's other mezzanines. Null when the room cannot host one.
+ */
+export function describeMezzanineHost(
+  nodes: Record<string, AnyNode>,
+  hostZoneId: string,
+): FloorRegionRoom | null {
+  const zone = nodes[hostZoneId]
+  if (zone?.type !== 'zone' || zone.floor?.support === 'open' || !zone.parentId) return null
+  const level = nodes[zone.parentId]
+  if (level?.type !== 'level') return null
+  const record = getRoomSelectionIndex(level.id)
+    .update(nodes)
+    .find((room) => room.zoneId === hostZoneId)
+  if (!record) return null
+  const clear: MultiPolygon = record.clearPolygon
+  const mezzanines = Object.values(nodes).flatMap((node) =>
+    node.type === 'zone' && node.floor?.support === 'open' && node.parentId === level.id
+      ? [node.polygon]
+      : [],
+  )
+  return {
+    zoneId: hostZoneId,
+    levelId: level.id,
+    clear,
+    elevation: defaultMezzanineElevation(level),
+    angle: floorRegionAxisAngle(clear),
+    targets: floorRegionSnapTargets(clear, mezzanines),
+    purpose: MEZZANINE,
+  }
+}
+
+/**
+ * Arms "Add mezzanine" in `hostZoneId`: select mode, the room's level and the
+ * room selected first, then the tool's gesture, so setting them up cannot
+ * cancel it. Returns false (changing nothing) when the room cannot host one.
+ */
+export function startMezzanineDraft(
+  hostZoneId: string,
+  shape: MezzanineShape = 'rectangle',
+): boolean {
+  const nodes = useScene.getState().nodes
+  if (useScene.getState().readOnly) return false
+  const host = describeMezzanineHost(nodes, hostZoneId)
+  if (!host) return false
+  cancelMezzanineDraft()
+  cancelFloorRegion()
+  useMezzanineDraft.setState({ shape })
+  if (useEditor.getState().mode !== 'select') useEditor.getState().setMode('select')
+  if (useViewer.getState().selection.levelId !== host.levelId)
+    useViewer.getState().setSelection({ levelId: host.levelId as LevelNode['id'] })
+  if (useEditor.getState().room?.zoneId !== hostZoneId)
+    useEditor.getState().selectRoom({ levelId: host.levelId, zoneId: hostZoneId })
+  beginTool(host)
+  return true
+}
+
+export function cancelMezzanineDraft() {
+  const current = tool
+  tool = null
+  if (current?.active) current.cancel()
+  else reset()
+}
+
+export function mezzanineDraftActive() {
+  return !!useMezzanineDraft.getState().host
+}
+
+/** Switches rectangle ↔ polygon; the outline in hand is dropped, the tool stays. */
+export function setMezzanineShape(shape: MezzanineShape) {
+  if (useMezzanineDraft.getState().shape === shape) return
+  const { draft } = useFloorRegionDraft.getState()
+  if (draft?.room.purpose === MEZZANINE) useFloorRegionDraft.setState({ draft: null })
+  useMezzanineDraft.setState({ shape })
+}

package/src/lib/mezzanine-messages.ts

@@ -0,0 +1,26 @@
+import { CROSSING_MESSAGE } from './floor-region-geometry'
+
+// Short labels for what core refuses a mezzanine — drawing, moving, turning,
+// copying, pushing an edge or adding its stair all read the same words.
+
+export const MEZZANINE_OUTSIDE_MESSAGE = 'Outside the room'
+export const MEZZANINE_TOO_SMALL_MESSAGE = 'At least 1 m²'
+export const MEZZANINE_OVERLAP_MESSAGE = 'Overlaps a mezzanine'
+export const MEZZANINE_ELEVATION_MESSAGE = 'Too high or too low'
+export const MEZZANINE_FAILED_MESSAGE = "Can't add a mezzanine here"
+export const MEZZANINE_NO_STAIR_MESSAGE = 'No room for stairs'
+
+const CONFLICT_MESSAGES: Record<string, string> = {
+  'outside-host': MEZZANINE_OUTSIDE_MESSAGE,
+  'overlaps-mezzanine': MEZZANINE_OVERLAP_MESSAGE,
+  'mezzanine-overlap': MEZZANINE_OVERLAP_MESSAGE,
+  'too-small': MEZZANINE_TOO_SMALL_MESSAGE,
+  'self-intersecting': CROSSING_MESSAGE,
+  'mezzanine-elevation': MEZZANINE_ELEVATION_MESSAGE,
+  'no-room-for-stair': MEZZANINE_NO_STAIR_MESSAGE,
+}
+
+/** The label for a core mezzanine conflict code, or null when it is not one of them. */
+export function mezzanineConflictMessage(code: string | undefined): string | null {
+  return (code && CONFLICT_MESSAGES[code]) || null
+}

package/src/lib/mezzanine-selection.test.ts

@@ -0,0 +1,207 @@
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  BuildingNode,
+  clearSceneHistory,
+  createMezzanine,
+  createZone,
+  deleteZone,
+  generateId,
+  initSpaceDetectionSync,
+  LevelNode,
+  type SlabNode,
+  useScene,
+  type ZoneNode,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { deleteConfirmationContent } from '../components/editor/delete-confirmation-dialog'
+import { resolveFloorRegionRoom } from '../components/editor/floor-region-controls'
+import { MEZZANINE_GESTURE_HINTS, mezzanineGesture } from '../components/ui/helpers/helper-manager'
+import {
+  MEZZANINE_EDGE_DRAG_LABEL,
+  mezzanineElevationBounds,
+  ROOM_ELEVATION_DRAG_LABEL,
+} from './room-handle-drag'
+import { RoomSelectionIndex, resolveRoomHit } from './room-selection'
+import { applyRoomPlan } from './room-structure-commands'
+import { ROOM_MOVE_DRAG_LABEL } from './room-transform-session'
+import { zoneAtLevelPoint } from './units'
+
+const LEVEL = 'level_mezzanine_selection'
+let hostId = '' as ZoneNode['id']
+let mezzanineId = '' as ZoneNode['id']
+let stop = () => {}
+const savedRaf = globalThis.requestAnimationFrame
+const savedCaf = globalThis.cancelAnimationFrame
+
+beforeEach(() => {
+  globalThis.requestAnimationFrame ??= ((callback: (time: number) => void) => {
+    callback(0)
+    return 0
+  }) as typeof requestAnimationFrame
+  globalThis.cancelAnimationFrame ??= (() => {}) as typeof cancelAnimationFrame
+  const building = BuildingNode.parse({ id: 'building_mezzanine_selection', children: [LEVEL] })
+  const level = LevelNode.parse({ id: LEVEL, parentId: building.id, height: 5 })
+  useScene.setState({
+    nodes: { [building.id]: building, [level.id]: level },
+    rootNodeIds: [building.id],
+    dirtyNodes: new Set(),
+    materials: {},
+    collections: {},
+    readOnly: false,
+  })
+  useScene.temporal.getState().resume()
+  stop = initSpaceDetectionSync(useScene, { getState: () => ({ spaces: {}, setSpaces: () => {} }) })
+  const host = createZone(useScene.getState().nodes, {
+    levelId: LEVEL,
+    polygon: [
+      [0, 0],
+      [8, 0],
+      [8, 6],
+      [0, 6],
+    ],
+    enclose: true,
+    mintId: generateId,
+  })
+  applyRoomPlan(host)
+  hostId = host.zoneId as ZoneNode['id']
+  const mezzanine = createMezzanine(useScene.getState().nodes, {
+    hostZoneId: hostId,
+    polygon: [
+      [0.5, 0.5],
+      [4, 0.5],
+      [4, 3],
+      [0.5, 3],
+    ],
+    mintId: generateId,
+  })
+  expect(mezzanine.conflicts ?? []).toEqual([])
+  applyRoomPlan(mezzanine)
+  mezzanineId = mezzanine.zoneId as ZoneNode['id']
+  useViewer.getState().setSelection({ buildingId: building.id, levelId: LEVEL, selectedIds: [] })
+  clearSceneHistory()
+})
+
+afterEach(() => stop())
+
+afterAll(() => {
+  globalThis.requestAnimationFrame = savedRaf
+  globalThis.cancelAnimationFrame = savedCaf
+})
+
+const nodes = () => useScene.getState().nodes as Record<string, AnyNode>
+
+describe('mezzanine selection', () => {
+  test('the room index lists the mezzanine as its own room beside the untouched host', () => {
+    const index = new RoomSelectionIndex(LEVEL)
+    const records = index.update(nodes())
+    const host = records.find((room) => room.zoneId === hostId)!
+    const mezzanine = records.find((room) => room.zoneId === mezzanineId)!
+    expect(host.mezzanine).toBeNull()
+    expect(host.area).toBeCloseTo(48, 0)
+    expect(mezzanine.mezzanine).toEqual({ hostZoneId: hostId })
+    expect(mezzanine.name).toBe('Mezzanine')
+    expect(mezzanine.area).toBeCloseTo(8.75)
+    expect(mezzanine.spans).toEqual([])
+    expect(mezzanine.boundaryWallIds).toEqual([])
+    const plate = nodes()[mezzanine.slabId as AnyNodeId] as SlabNode
+    expect(plate.support).toBe('open')
+    expect(host.slabId).not.toBe(mezzanine.slabId)
+  })
+
+  test('the mezzanine plate and railing pick the mezzanine; the host floor under it picks the host', () => {
+    const index = new RoomSelectionIndex(LEVEL)
+    const records = index.update(nodes())
+    const mezzanine = records.find((room) => room.zoneId === mezzanineId)!
+    const host = records.find((room) => room.zoneId === hostId)!
+    const plate = nodes()[mezzanine.slabId as AnyNodeId]!
+    const hostFloor = nodes()[host.slabId as AnyNodeId]!
+    // Anywhere on the mezzanine plate — its top, underside or a railing post.
+    expect(resolveRoomHit(index, LEVEL, plate, [2, 1.5], '3d')?.key.zoneId).toBe(mezzanineId)
+    expect(resolveRoomHit(index, LEVEL, plate, [3.99, 2.99], '3d')?.key.zoneId).toBe(mezzanineId)
+    // The host floor under the mezzanine, and a point-only (plan) hit there.
+    expect(resolveRoomHit(index, LEVEL, hostFloor, [2, 1.5], '3d')?.key.zoneId).toBe(hostId)
+    expect(resolveRoomHit(index, LEVEL, null, [2, 1.5])?.key.zoneId).toBe(hostId)
+    expect(resolveRoomHit(index, LEVEL, hostFloor, [6, 4], '3d')?.key.zoneId).toBe(hostId)
+  })
+
+  test('units pick the zone by the hit height: on the mezzanine or under it', () => {
+    const elevation = (nodes()[mezzanineId as AnyNodeId] as ZoneNode).floor!.elevation!
+    expect(elevation).toBeCloseTo(2.5)
+    expect(zoneAtLevelPoint(2, 1.5, elevation)?.id).toBe(mezzanineId)
+    expect(zoneAtLevelPoint(2, 1.5, elevation - 0.2)?.id).toBe(mezzanineId)
+    expect(zoneAtLevelPoint(2, 1.5, 0.05)?.id).toBe(hostId)
+    expect(zoneAtLevelPoint(6, 4, elevation)?.id).toBe(hostId)
+    // No height (the plan, from above): the mezzanine on top.
+    expect(zoneAtLevelPoint(2, 1.5)?.id).toBe(mezzanineId)
+  })
+
+  test('the elevation handle stays inside the heights core accepts', () => {
+    expect(mezzanineElevationBounds(nodes(), hostId)).toBeNull()
+    const bounds = mezzanineElevationBounds(nodes(), mezzanineId)!
+    expect(bounds.min).toBeCloseTo(0.21)
+    expect(bounds.max).toBeCloseTo(4.7)
+  })
+
+  test('a mezzanine covering its whole host still wins on its plate (units)', () => {
+    // Stretch the mezzanine over the host's whole footprint: same area, host listed first.
+    const hostPolygon = (nodes()[hostId as AnyNodeId] as ZoneNode).polygon
+    useScene.getState().updateNode(mezzanineId as AnyNodeId, { polygon: hostPolygon } as never)
+    const elevation = (nodes()[mezzanineId as AnyNodeId] as ZoneNode).floor!.elevation!
+    expect(zoneAtLevelPoint(2, 1.5, elevation)?.id).toBe(mezzanineId)
+    expect(zoneAtLevelPoint(6, 4, elevation)?.id).toBe(mezzanineId)
+    expect(zoneAtLevelPoint(6, 4)?.id).toBe(mezzanineId)
+    expect(zoneAtLevelPoint(2, 1.5, 0.05)?.id).toBe(hostId)
+  })
+
+  test('plan-view floor drafts pick the topmost floor: the mezzanine over its host', () => {
+    expect(resolveFloorRegionRoom(LEVEL, [2, 1.5])?.zoneId).toBe(mezzanineId)
+    expect(resolveFloorRegionRoom(LEVEL, [6, 4])?.zoneId).toBe(hostId)
+  })
+
+  test('raising, resizing and moving a mezzanine are titled Mezzanine; a room keeps its HUDs', () => {
+    const gesture = (nodeId: string, label: string) => mezzanineGesture({ nodeId, label }, nodes())
+    expect(gesture(mezzanineId, ROOM_ELEVATION_DRAG_LABEL)).toBe('raise')
+    expect(gesture(mezzanineId, MEZZANINE_EDGE_DRAG_LABEL)).toBe('resize')
+    expect(gesture(mezzanineId, ROOM_MOVE_DRAG_LABEL)).toBe('move')
+    expect(gesture(hostId, ROOM_ELEVATION_DRAG_LABEL)).toBeNull()
+    expect(gesture(hostId, ROOM_MOVE_DRAG_LABEL)).toBeNull()
+    expect(gesture(mezzanineId, 'height')).toBeNull()
+    expect(mezzanineGesture(null, nodes())).toBeNull()
+    expect(MEZZANINE_GESTURE_HINTS.move[0]!.label).toBe('Place inside the room')
+  })
+
+  test('the delete dialog speaks of the mezzanine, and of its items only when it has some', () => {
+    const request = (contents: 'delete' | 'keep' = 'delete') => ({
+      count: 1,
+      room: deleteZone(nodes(), { zoneId: mezzanineId, contents }).payload,
+      onConfirm: () => {},
+      onKeepContents: () => {},
+    })
+    const empty = deleteConfirmationContent(request(), nodes())
+    expect(empty.title).toBe('Delete Mezzanine?')
+    expect(empty.description).toMatch(/^Removes the mezzanine floor/)
+    expect(empty.description).not.toContain('item')
+    expect(empty.keepLabel).toBeNull()
+    const hasCeiling = Object.values(nodes()).some(
+      (node) => node.type === 'ceiling' && node.zoneId === mezzanineId,
+    )
+    expect(empty.description.includes('ceiling')).toBe(hasCeiling)
+    const withItems = request()
+    withItems.room = { ...withItems.room, itemIds: ['item_a', 'item_b'] }
+    const loaded = deleteConfirmationContent(withItems, nodes())
+    expect(loaded.description).toContain('2 items are on it. Keep them on the floor below')
+    expect(loaded.keepLabel).toBe('Keep items')
+    // A room's dialog is unchanged.
+    const room = deleteConfirmationContent(
+      {
+        count: 1,
+        room: deleteZone(nodes(), { zoneId: hostId, contents: 'delete' }).payload,
+        onConfirm: () => {},
+      },
+      nodes(),
+    )
+    expect(room.description).not.toContain('mezzanine')
+  })
+})

package/src/lib/mezzanine-stairs.ts

@@ -0,0 +1,46 @@
+import {
+  type AnyNodeId,
+  planMezzanineStair,
+  runAsSingleSceneHistoryStep,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import useEditor from '../store/use-editor'
+import { MEZZANINE_NO_STAIR_MESSAGE, mezzanineConflictMessage } from './mezzanine-messages'
+import { applyRoomPlan } from './room-structure-commands'
+import { sfxEmitter } from './sfx-bus'
+
+export type MezzanineStairResult = { ok: true; stairId: string } | { ok: false; message: string }
+
+/**
+ * "Add stairs": core places a straight flight from the host floor up to one of
+ * the mezzanine's open edges (its railing opens there), as one undo step. The
+ * new stair is selected, like a new mezzanine is, so it can be adjusted at once.
+ */
+export function addMezzanineStairs(zoneId: string): MezzanineStairResult {
+  const nodes = useScene.getState().nodes
+  if (useScene.getState().readOnly || !nodes[zoneId as AnyNodeId])
+    return { ok: false, message: MEZZANINE_NO_STAIR_MESSAGE }
+  let plan: ReturnType<typeof planMezzanineStair>
+  try {
+    plan = planMezzanineStair(nodes, zoneId)
+  } catch {
+    return { ok: false, message: MEZZANINE_NO_STAIR_MESSAGE }
+  }
+  const conflict = plan.conflicts?.[0]
+  if (conflict || !plan.stairId)
+    return {
+      ok: false,
+      message: mezzanineConflictMessage(conflict?.code) ?? MEZZANINE_NO_STAIR_MESSAGE,
+    }
+  // The stair and its flight land as one step.
+  let applied = false
+  runAsSingleSceneHistoryStep(useScene, () => {
+    applied = applyRoomPlan(plan)
+  })
+  if (!applied) return { ok: false, message: MEZZANINE_NO_STAIR_MESSAGE }
+  sfxEmitter.emit('sfx:structure-build')
+  useEditor.getState().clearRoom()
+  useViewer.getState().setSelection({ selectedIds: [plan.stairId as AnyNodeId] })
+  return { ok: true, stairId: plan.stairId! }
+}

package/src/lib/model-export.ts

@@ -1,12 +1,14 @@
 import type { GlbExportOptions } from './glb-export'
 
-export type ModelExportFormat = 'glb' | 'usdz' | 'stl' | 'obj' | 'print-stl' | 'print-3mf'
+export type ModelExportFormat = 'glb' | 'usdz' | 'stl' | 'obj' | 'ifc' | 'print-stl' | 'print-3mf'
 
 export type ModelExportOptions = Pick<
   GlbExportOptions,
   'onlyVisible' | 'excludedNodeTypes' | 'includedPresentationIds'
 > & {
   download?: boolean
+  /** Names the IFC project and its file. */
+  projectName?: string
   printScale?: number
   printScope?: 'whole' | 'levels'
   printContent?: 'structure' | 'everything'

package/src/lib/node-action-movement.ts

@@ -1,4 +1,13 @@
-import { type AnyNode, createSceneApi, isMovable, nodeRegistry, useScene } from '@pascal-app/core'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  cloneNodesInto,
+  collectSubtree,
+  isMovable,
+  nodeRegistry,
+  useScene,
+} from '@pascal-app/core'
+import { copyCreateOps } from './fresh-planar-placement'
 
 export function registryMoveDisabled(node: AnyNode): boolean {
   const def = nodeRegistry.get(node.type)
@@ -11,11 +20,13 @@ export function registryMoveDisabled(node: AnyNode): boolean {
 }
 
 export function duplicateWithoutMove(node: AnyNode) {
-  const api = createSceneApi(useScene)
-  const subtree = api.getSubtree(node.id)
-  if (!subtree || !node.parentId) return null
-  return api.cloneNodesInto([subtree.root, ...subtree.descendants], {
+  const subtree = collectSubtree(useScene.getState().nodes, node.id)
+  const parentId = node.parentId as AnyNodeId | null
+  if (!subtree || !parentId) return null
+  const cloned = cloneNodesInto([subtree.root, ...subtree.descendants], {
     rootId: node.id,
-    parentId: node.parentId as AnyNode['id'],
+    parentId,
   })
+  useScene.getState().createNodes(copyCreateOps(cloned, parentId))
+  return cloned.rootId
 }

package/src/lib/node-display-label.ts

@@ -0,0 +1,37 @@
+import type { AnyNode } from '@pascal-app/core'
+
+/**
+ * A node's human label, the same in the baked artifact (`extras.label`) and the
+ * viewer's breadcrumb: an explicit name wins, items fall back to their catalog
+ * asset name, other kinds to a type word.
+ */
+export function nodeDisplayLabel(node: AnyNode): string {
+  if (node.name) return node.name
+  switch (node.type) {
+    case 'item':
+      return (node as { asset?: { name?: string } }).asset?.name || 'Item'
+    case 'wall':
+      return 'Wall'
+    case 'door':
+      return 'Door'
+    case 'window':
+      return 'Window'
+    case 'cabinet':
+    case 'cabinet-module':
+      return 'Cabinet'
+    case 'slab':
+      return 'Slab'
+    case 'ceiling':
+      return 'Ceiling'
+    case 'roof':
+      return 'Roof'
+    case 'fence':
+      return 'Fence'
+    case 'column':
+      return 'Column'
+    case 'stair':
+      return 'Stairs'
+    default:
+      return node.type
+  }
+}