@pascal-app/editor 1.0.3 → 1.0.4

package/src/lib/lot/terrain.ts

@@ -0,0 +1,266 @@
+/**
+ * Lot terrain from USGS elevations: an N×N grid of points over the lot's
+ * bounding box (padded a touch so the ground runs past the lines) goes to
+ * the parcel provider's `elevation` (USGS EPQS, feet), the readings come
+ * back relative to a DATUM — the ground at the lot's centre, so the site
+ * plane y = 0 is the ground where the house will stand — and are written
+ * into the site's heightfield (`site.terrain`, the same field the sculpt
+ * tool edits and every placement / raycast / drape reads).
+ *
+ * Honesty: a web-service DEM is preliminary — the sample record on the
+ * site (`metadata.terrainSample`: source, grid, holes, datum, relief) says
+ * what was read; a lot flatter than `MIN_RELIEF_M` writes NO terrain and
+ * keeps the flat-ground fast path; every failure returns a reason and
+ * writes nothing.
+ */
+import {
+  commitTerrainField,
+  createTerrainField,
+  quantize,
+  type TerrainData,
+  type TerrainField,
+} from '@pascal-app/core'
+import { getParcelProvider, NO_PARCEL_SERVICE, type ParcelProvider } from './parcel-provider'
+
+export type Pt = readonly [number, number]
+
+/** apps/editor/lib/parcel/project.ts — the plan frame's degree scale. */
+export const FEET_PER_DEG_LAT = 364000
+const METRES_PER_FOOT = 0.3048
+const DEG2RAD = Math.PI / 180
+/** Grid points per side (81 points — well under the route's 256 cap). */
+export const DEFAULT_GRID_N = 9
+/** The lot bbox is padded by this fraction so the mesh runs past the lines. */
+export const PAD_FRAC = 0.08
+/** A lot with less fall than this across its samples is flat: no terrain written. */
+export const MIN_RELIEF_M = 0.15
+/** Heightfield resolution: the bbox split into ~64 cells per side, clamped. */
+const FIELD_CELLS = 64
+const MIN_SPACING_M = 0.5
+const MAX_SPACING_M = 4
+
+export interface TerrainSampleSummary {
+  source: 'USGS EPQS'
+  /** Grid side (n × n points). */
+  grid: number
+  /** Points with a reading / without one. */
+  sampled: number
+  holes: number
+  /** Absolute elevation of the site plane (the datum), feet. */
+  datumFt: number
+  /** Highest − lowest reading, feet. */
+  reliefFt: number
+  /** True when the lot read flat and no heightfield was written. */
+  flat: boolean
+  at: string
+}
+
+export interface TerrainSampleResult {
+  ok: boolean
+  reason?: string
+  /** The heightfield to write to `site.terrain` (absent when flat). */
+  terrain?: TerrainData
+  summary?: TerrainSampleSummary
+}
+
+export interface SampleGrid {
+  n: number
+  x0: number
+  z0: number
+  x1: number
+  z1: number
+  /** Row-major, `r * n + c`. */
+  points: Pt[]
+}
+
+/** Local plan metres (the site frame) → `{ lat, lng }`, the inverse of `ringsToPlanFeet`. */
+export function localMetresToLngLat(
+  p: Pt,
+  originLngLat: readonly [number, number],
+): { lat: number; lng: number } {
+  const [oLng, oLat] = originLngLat
+  const ftPerDegLng = FEET_PER_DEG_LAT * Math.cos(oLat * DEG2RAD)
+  const xFt = p[0] / METRES_PER_FOOT
+  const zFt = p[1] / METRES_PER_FOOT
+  return { lng: oLng + xFt / ftPerDegLng, lat: oLat - zFt / FEET_PER_DEG_LAT }
+}
+
+/** The n × n sample grid over the ring's padded bounding box. */
+export function gridOver(ring: readonly Pt[], n = DEFAULT_GRID_N, pad = PAD_FRAC): SampleGrid {
+  let minX = Number.POSITIVE_INFINITY
+  let minZ = Number.POSITIVE_INFINITY
+  let maxX = Number.NEGATIVE_INFINITY
+  let maxZ = Number.NEGATIVE_INFINITY
+  for (const p of ring) {
+    minX = Math.min(minX, p[0])
+    maxX = Math.max(maxX, p[0])
+    minZ = Math.min(minZ, p[1])
+    maxZ = Math.max(maxZ, p[1])
+  }
+  const padX = (maxX - minX) * pad
+  const padZ = (maxZ - minZ) * pad
+  const x0 = minX - padX
+  const x1 = maxX + padX
+  const z0 = minZ - padZ
+  const z1 = maxZ + padZ
+  const side = Math.max(2, Math.floor(n))
+  const points: Pt[] = []
+  for (let r = 0; r < side; r++) {
+    const z = z0 + ((z1 - z0) * r) / (side - 1)
+    for (let c = 0; c < side; c++) points.push([x0 + ((x1 - x0) * c) / (side - 1), z])
+  }
+  return { n: side, x0, z0, x1, z1, points }
+}
+
+/**
+ * Bilinear read of the coarse grid at a plan point; holes (null readings)
+ * read as `fill`. Clamped to the grid — the field never extrapolates.
+ */
+export function coarseHeightAt(
+  grid: SampleGrid,
+  elev: readonly (number | null)[],
+  x: number,
+  z: number,
+  fill: number,
+): number {
+  const n = grid.n
+  const fx = grid.x1 === grid.x0 ? 0 : ((x - grid.x0) / (grid.x1 - grid.x0)) * (n - 1)
+  const fz = grid.z1 === grid.z0 ? 0 : ((z - grid.z0) / (grid.z1 - grid.z0)) * (n - 1)
+  const gx = Math.max(0, Math.min(n - 1, fx))
+  const gz = Math.max(0, Math.min(n - 1, fz))
+  const c0 = Math.min(n - 2, Math.floor(gx))
+  const r0 = Math.min(n - 2, Math.floor(gz))
+  const tx = gx - c0
+  const tz = gz - r0
+  const at = (r: number, c: number): number => {
+    const v = elev[r * n + c]
+    return v === null || v === undefined || !Number.isFinite(v) ? fill : v
+  }
+  const top = at(r0, c0) * (1 - tx) + at(r0, c0 + 1) * tx
+  const bottom = at(r0 + 1, c0) * (1 - tx) + at(r0 + 1, c0 + 1) * tx
+  return top * (1 - tz) + bottom * tz
+}
+
+/** A heightfield over the grid's extent, metres above the datum, bilinear from the coarse samples. */
+export function fieldFromSamples(
+  grid: SampleGrid,
+  elevM: readonly (number | null)[],
+  datumM: number,
+  fillM: number,
+): TerrainField {
+  const spanX = grid.x1 - grid.x0
+  const spanZ = grid.z1 - grid.z0
+  const spacing = Math.min(
+    MAX_SPACING_M,
+    Math.max(MIN_SPACING_M, Math.max(spanX, spanZ) / FIELD_CELLS),
+  )
+  const cols = Math.max(2, Math.ceil(spanX / spacing) + 1)
+  const rows = Math.max(2, Math.ceil(spanZ / spacing) + 1)
+  const field = createTerrainField({ origin: [grid.x0, grid.z0], spacing, cols, rows })
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const x = grid.x0 + c * spacing
+      const z = grid.z0 + r * spacing
+      field.heights[r * cols + c] = quantize(
+        field,
+        coarseHeightAt(grid, elevM, x, z, fillM) - datumM,
+      )
+    }
+  }
+  return field
+}
+
+type ElevationResponse = {
+  ok?: boolean
+  error?: string
+  results?: { lat?: number; lng?: number; elevation?: number | null }[]
+}
+
+export interface SampleOptions {
+  /** Default = the provider the host set. */
+  provider?: ParcelProvider
+  /** Grid side, default 9. */
+  n?: number
+  /** Passed to the route (USGS is slow; the route caps it). */
+  deadlineMs?: number
+  /** Where the datum is read (site metres); default = the ring's centroid. */
+  datumAt?: Pt
+  now?: () => string
+}
+
+/**
+ * Sample the lot. Resolves `{ ok: false, reason }` on every failure path and
+ * never throws; `ok: true` with no `terrain` means the lot read flat.
+ */
+export async function sampleLotTerrain(
+  ring: readonly Pt[],
+  originLngLat: readonly [number, number],
+  options: SampleOptions = {},
+): Promise<TerrainSampleResult> {
+  if (ring.length < 3) return { ok: false, reason: 'no lot ring' }
+  const provider = options.provider ?? getParcelProvider()
+  if (!provider) return { ok: false, reason: NO_PARCEL_SERVICE }
+  const grid = gridOver(ring, options.n ?? DEFAULT_GRID_N)
+  const points = grid.points.map((p) => localMetresToLngLat(p, originLngLat))
+  let body: ElevationResponse
+  try {
+    body = (await provider('elevation', {
+      points,
+      deadlineMs: options.deadlineMs ?? 12000,
+    })) as ElevationResponse
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : 'elevation lookup failed' }
+  }
+  if (!body.ok || !Array.isArray(body.results))
+    return { ok: false, reason: body.error ?? 'no elevations' }
+  const elevFt: (number | null)[] = grid.points.map((_, i) => {
+    const e = body.results?.[i]?.elevation
+    return typeof e === 'number' && Number.isFinite(e) ? e : null
+  })
+  const valid = elevFt.filter((e): e is number => e !== null)
+  if (valid.length < 4)
+    return { ok: false, reason: `too few elevations (${valid.length} of ${elevFt.length})` }
+  const mean = valid.reduce((s, v) => s + v, 0) / valid.length
+  const datumAt = options.datumAt ?? centroidOf(ring)
+  const datumFt = coarseHeightAt(grid, elevFt, datumAt[0], datumAt[1], mean)
+  const reliefFt = Math.max(...valid) - Math.min(...valid)
+  const summary: TerrainSampleSummary = {
+    source: 'USGS EPQS',
+    grid: grid.n,
+    sampled: valid.length,
+    holes: elevFt.length - valid.length,
+    datumFt,
+    reliefFt,
+    flat: reliefFt * METRES_PER_FOOT < MIN_RELIEF_M,
+    at: (options.now ?? (() => new Date().toISOString()))(),
+  }
+  if (summary.flat) return { ok: true, summary }
+  const elevM = elevFt.map((e) => (e === null ? null : e * METRES_PER_FOOT))
+  const field = fieldFromSamples(grid, elevM, datumFt * METRES_PER_FOOT, mean * METRES_PER_FOOT)
+  return { ok: true, terrain: commitTerrainField(field), summary }
+}
+
+function centroidOf(ring: readonly Pt[]): Pt {
+  let x = 0
+  let z = 0
+  for (const p of ring) {
+    x += p[0]
+    z += p[1]
+  }
+  return [x / ring.length, z / ring.length]
+}
+
+/** One status fragment for the drop-in message. */
+export function describeTerrainSample(
+  summary: TerrainSampleSummary | null,
+  failure: string,
+): string {
+  if (summary) {
+    if (summary.flat) return `ground flat within ${Math.round(summary.reliefFt * 12)}" (USGS)`
+    const holes = summary.holes > 0 ? `, ${summary.holes} unread` : ''
+    return `terrain: ${summary.reliefFt.toFixed(1)}' of fall across the lot (USGS, ${summary.sampled} pts${holes})`
+  }
+  if (failure && failure !== 'skipped')
+    return `terrain read failed (${failure}) — the ground is flat until it is read`
+  return ''
+}

package/src/lib/material-catalog-model.ts

@@ -25,6 +25,8 @@ export function useMaterialCatalogModel(
   selectedMaterialPreset?: string,
   onSelectMaterialPreset?: (ref: string) => void,
   disabled = false,
+  /** Paint mode arms the tab's first material; a finish row only writes on a tile click. */
+  selectOnCategoryChange = true,
 ) {
   const [selectedCategory, setCategory] = useState<(typeof MATERIAL_CATEGORIES)[number]>(
     MATERIAL_CATEGORIES[0],
@@ -57,7 +59,7 @@ export function useMaterialCatalogModel(
   const setSelectedCategory = (category: typeof selectedCategory) => {
     setCategory(category)
     const first = itemsFor(category)[0]
-    if (first) select(first.id)
+    if (first && selectOnCategoryChange) select(first.id)
   }
   return {
     selectedCategory,

package/src/lib/material-paint-panel-model.ts

@@ -10,14 +10,13 @@ import { useViewer } from '@pascal-app/viewer'
 import { useEffect } from 'react'
 import useEditor from '../store/use-editor'
 import { buildResetSurfaceMaterialUpdates, resolvePaintTargetFromSelection } from './material-paint'
+import { usePaintRegionMode } from './paint-region-mode'
 
 export function useMaterialPaintPanelModel(enabled = true) {
   const activePaintMaterial = useEditor((state) => state.activePaintMaterial)
   const activePaintTarget = useEditor((state) => state.activePaintTarget)
   const setActivePaintMaterial = useEditor((state) => state.armMaterialPaint)
   const setActivePaintTarget = useEditor((state) => state.setActivePaintTarget)
-  const paintEraser = useEditor((state) => state.paintEraser)
-  const setPaintEraser = useEditor((state) => state.setPaintEraser)
   const selectedId = useViewer((state) =>
     state.selection.selectedIds.length === 1 ? (state.selection.selectedIds[0] ?? null) : null,
   )
@@ -25,15 +24,20 @@ export function useMaterialPaintPanelModel(enabled = true) {
     resolvePaintTargetFromSelection({ nodes: state.nodes, selectedId }),
   )
   const materials = useScene((state) => state.materials)
+  const paintEraser = usePaintRegionMode((state) => state.mode === 'erase')
+  const setPaintEraser = (on: boolean) => {
+    const paintMode = usePaintRegionMode.getState()
+    paintMode.setMode(on ? 'erase' : paintMode.drawMode)
+  }
   const canResetSelection = paintTarget !== null
-  useEffect(() => {
-    if (enabled && paintTarget) setActivePaintTarget(paintTarget)
-  }, [enabled, paintTarget, setActivePaintTarget])
   const resetSelection = () => {
     const scene = useScene.getState()
     const node = selectedId ? scene.nodes[selectedId as AnyNodeId] : undefined
     if (node) scene.updateNodes(buildResetSurfaceMaterialUpdates(scene.nodes, node))
   }
+  useEffect(() => {
+    if (enabled && paintTarget) setActivePaintTarget(paintTarget)
+  }, [enabled, paintTarget, setActivePaintTarget])
   const createCustomMaterial = () => {
     const scene = useScene.getState()
     const id = generateSceneMaterialId()

package/src/lib/material-paint.ts

@@ -21,6 +21,8 @@ import {
   type RoofSegmentNode,
   type RoofSegmentSurfaceMaterialRole,
   type RoofSurfaceMaterialRole,
+  type SceneMaterial,
+  type SceneMaterialId,
   type ShelfNode,
   type SlabNode,
   type StairNode,
@@ -243,6 +245,7 @@ export function getEffectiveChimneyMaterial(
 }
 
 export function resolveActivePaintMaterialFromSelection(params: {
+  materials?: Record<SceneMaterialId, SceneMaterial>
   nodes: Record<string, any>
   selectedId: string | null
   selectedMaterialTarget: {
@@ -274,6 +277,7 @@ export function resolveActivePaintMaterialFromSelection(params: {
       node: selectedNode,
       role: selectedMaterialTarget.role as string,
       nodes,
+      materials: params.materials,
     })
     if (surface) {
       const sourceTarget = (paintCap.materialTarget ?? selectedNode.type) as PaintableMaterialTarget

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

@@ -0,0 +1,342 @@
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  BuildingNode,
+  clearSceneHistory,
+  createMezzanine,
+  createZone,
+  generateId,
+  initSpaceDetectionSync,
+  LevelNode,
+  type Point,
+  useScene,
+  type ZoneNode,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { roomTransformSource } from '../components/editor/room-controls'
+import { runHistoryShortcut } from '../hooks/use-keyboard'
+import { getRoomSelectionIndex } from '../hooks/use-selected-room'
+import useEditor from '../store/use-editor'
+import useInteractionScope from '../store/use-interaction-scope'
+import { cancelGestures, hasLiveGestures } from './gesture-lifecycle'
+import {
+  MEZZANINE_NO_STAIR_MESSAGE,
+  MEZZANINE_OUTSIDE_MESSAGE,
+  MEZZANINE_OVERLAP_MESSAGE,
+} from './mezzanine-messages'
+import { addMezzanineStairs } from './mezzanine-stairs'
+import {
+  mezzanineEdgeHandles,
+  planMezzanineEdge,
+  runMezzanineEdgeDrag,
+  useRoomHandleDrag,
+} from './room-handle-drag'
+import { applyRoomPlan } from './room-structure-commands'
+import {
+  cancelRoomTransform,
+  commitRoomTransform,
+  previewRoomTransform,
+  rotateRoom,
+  startRoomTransform,
+  useRoomTransform,
+} from './room-transform-session'
+
+// A mezzanine picked up, turned, copied, pushed at an edge and given stairs:
+// core refuses what leaves its host or overlaps another mezzanine, and every
+// accepted action is one undo step that keeps the host link.
+
+const LEVEL = 'level_mezzanine_actions'
+const saved = {
+  window: globalThis.window,
+  document: globalThis.document,
+  raf: globalThis.requestAnimationFrame,
+  caf: globalThis.cancelAnimationFrame,
+}
+let hostId = ''
+let mezzanineId = ''
+let stop = () => {}
+
+const nodes = () => useScene.getState().nodes as Record<string, AnyNode>
+const zone = (id: string) => nodes()[id as AnyNodeId] as ZoneNode
+const mezzanines = () =>
+  Object.values(nodes()).filter(
+    (node): node is ZoneNode => node.type === 'zone' && node.floor?.support === 'open',
+  )
+const history = () => useScene.temporal.getState().pastStates.length
+const bounds = (polygon: readonly Point[]) => {
+  const xs = polygon.map(([x]) => x)
+  const zs = polygon.map(([, z]) => z)
+  return [Math.min(...xs), Math.min(...zs), Math.max(...xs), Math.max(...zs)]
+}
+
+function addMezzanine(polygon: Point[]) {
+  const plan = createMezzanine(nodes(), { hostZoneId: hostId, polygon, mintId: generateId })
+  expect(plan.conflicts ?? []).toEqual([])
+  applyRoomPlan(plan)
+  return plan.zoneId
+}
+
+function mezzanineRecord(id = mezzanineId) {
+  return getRoomSelectionIndex(LEVEL)
+    .update(nodes())
+    .find((room) => room.zoneId === id)!
+}
+
+beforeEach(() => {
+  cancelGestures('cancel')
+  globalThis.window = new EventTarget() as Window & typeof globalThis
+  globalThis.document = { body: { style: { cursor: '' } } } as unknown as Document
+  globalThis.requestAnimationFrame = ((callback: (time: number) => void) => {
+    callback(0)
+    return 0
+  }) as typeof requestAnimationFrame
+  globalThis.cancelAnimationFrame = (() => {}) as typeof cancelAnimationFrame
+  useInteractionScope.getState().end()
+  const building = BuildingNode.parse({ id: 'building_mezzanine_actions', 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(nodes(), {
+    levelId: LEVEL,
+    polygon: [
+      [0, 0],
+      [8, 0],
+      [8, 6],
+      [0, 6],
+    ],
+    enclose: true,
+    mintId: generateId,
+  })
+  applyRoomPlan(host)
+  hostId = host.zoneId
+  mezzanineId = addMezzanine([
+    [1, 1],
+    [4, 1],
+    [4, 3],
+    [1, 3],
+  ])
+  useViewer.getState().setSelection({ buildingId: building.id, levelId: LEVEL, selectedIds: [] })
+  useEditor.setState({
+    phase: 'building',
+    mode: 'select',
+    room: { levelId: LEVEL, zoneId: mezzanineId },
+    gridSnapStep: 0.5,
+  })
+  clearSceneHistory()
+})
+
+afterEach(() => {
+  cancelRoomTransform()
+  cancelGestures('cancel')
+  stop()
+})
+
+afterAll(async () => {
+  await new Promise((resolve) => setTimeout(resolve, 350))
+  globalThis.window = saved.window
+  globalThis.document = saved.document
+  globalThis.requestAnimationFrame = saved.raf
+  globalThis.cancelAnimationFrame = saved.caf
+})
+
+describe('moving a mezzanine', () => {
+  test('inside its host it commits in one step, keeping the host link', () => {
+    expect(startRoomTransform('move', roomTransformSource(mezzanineRecord()))).toBe(true)
+    previewRoomTransform([2, 1], 0)
+    expect(useRoomTransform.getState().session).toMatchObject({ valid: true })
+    expect(commitRoomTransform()).toBe(true)
+    expect(bounds(zone(mezzanineId).polygon)).toEqual([3, 2, 6, 4])
+    expect(zone(mezzanineId).hostZoneId).toBe(hostId)
+    expect(history()).toBe(1)
+  })
+
+  test('outside the host or onto another mezzanine it turns red with the mezzanine label', () => {
+    addMezzanine([
+      [5, 3.5],
+      [7.5, 3.5],
+      [7.5, 5.5],
+      [5, 5.5],
+    ])
+    clearSceneHistory()
+    startRoomTransform('move', roomTransformSource(mezzanineRecord()))
+    previewRoomTransform([6, 0], 0)
+    expect(useRoomTransform.getState().session).toMatchObject({
+      valid: false,
+      message: MEZZANINE_OUTSIDE_MESSAGE,
+    })
+    expect(commitRoomTransform()).toBe(false)
+    previewRoomTransform([1.5, 1], 0)
+    expect(useRoomTransform.getState().session).toMatchObject({
+      valid: false,
+      message: MEZZANINE_OVERLAP_MESSAGE,
+    })
+    expect(commitRoomTransform()).toBe(false)
+    expect(history()).toBe(0)
+  })
+})
+
+describe('turning and copying a mezzanine', () => {
+  test('rotate left turns it about its centre in one step; a turn that leaves the room says why', () => {
+    expect(rotateRoom({ levelId: LEVEL, zoneId: mezzanineId }, 'left').ok).toBe(true)
+    const [minX, minZ, maxX, maxZ] = bounds(zone(mezzanineId).polygon)
+    expect(maxX! - minX!).toBeCloseTo(2)
+    expect(maxZ! - minZ!).toBeCloseTo(3)
+    expect(history()).toBe(1)
+    // A long thin mezzanine along the room cannot turn across it.
+    const long = addMezzanine([
+      [0.5, 4.2],
+      [7.5, 4.2],
+      [7.5, 5.5],
+      [0.5, 5.5],
+    ])
+    clearSceneHistory()
+    const refused = rotateRoom({ levelId: LEVEL, zoneId: long }, 'right')
+    expect(refused).toMatchObject({ ok: false })
+    expect(useRoomTransform.getState().notice?.zoneId).toBe(long)
+    expect(history()).toBe(0)
+  })
+
+  test('duplicate places a copy hosted by the same room in one step', () => {
+    startRoomTransform('duplicate', roomTransformSource(mezzanineRecord()))
+    previewRoomTransform([0, 0], 0)
+    expect(useRoomTransform.getState().session).toMatchObject({
+      valid: false,
+      message: MEZZANINE_OVERLAP_MESSAGE,
+    })
+    previewRoomTransform([3.5, 0], 0)
+    expect(useRoomTransform.getState().session).toMatchObject({ valid: true })
+    expect(commitRoomTransform()).toBe(true)
+    expect(mezzanines()).toHaveLength(2)
+    expect(mezzanines().every((node) => node.hostZoneId === hostId)).toBe(true)
+    expect(history()).toBe(1)
+  })
+})
+
+describe('pushing a mezzanine edge', () => {
+  test('one arrow per edge, pointing out of the mezzanine', () => {
+    const handles = mezzanineEdgeHandles(nodes(), mezzanineId)
+    expect(handles).toHaveLength(4)
+    for (const handle of handles) {
+      const plan = planMezzanineEdge(nodes(), mezzanineId, handle.edgeIndex, 0.4)
+      expect(plan.conflicts ?? []).toEqual([])
+      const update = plan.changes.find((change) => change.op === 'update')
+      const polygon = (update as { data: { polygon: Point[] } }).data.polygon
+      // Pushing outward grows the plate.
+      const [a, b, c, d] = bounds(polygon)
+      expect((c! - a!) * (d! - b!)).toBeGreaterThan(3 * 2)
+    }
+  })
+
+  test('a drag previews the outline, refuses outside the room and commits in one step', () => {
+    const east = mezzanineEdgeHandles(nodes(), mezzanineId).find(
+      (handle) => handle.outward[0] > 0.9,
+    )!
+    let at = 0
+    runMezzanineEdgeDrag({
+      handle: east,
+      zoneId: mezzanineId,
+      levelId: LEVEL,
+      from: 0,
+      along: () => at,
+    })
+    const move = (value: number) => {
+      at = value
+      window.dispatchEvent(Object.assign(new Event('pointermove'), { clientX: 1, clientY: 1 }))
+    }
+    move(10)
+    expect(useRoomHandleDrag.getState().drag).toMatchObject({
+      kind: 'mezzanine-edge',
+      message: MEZZANINE_OUTSIDE_MESSAGE,
+    })
+    move(1)
+    const drag = useRoomHandleDrag.getState().drag as { message?: string; outline: Point[] }
+    expect(drag.message).toBeUndefined()
+    expect(bounds(drag.outline)[2]).toBeCloseTo(5)
+    // Nothing is written until release.
+    expect(bounds(zone(mezzanineId).polygon)[2]).toBeCloseTo(4)
+    window.dispatchEvent(Object.assign(new Event('pointerup'), { clientX: 1, clientY: 1 }))
+    expect(bounds(zone(mezzanineId).polygon)[2]).toBeCloseTo(5)
+    expect(history()).toBe(1)
+    expect(hasLiveGestures()).toBe(false)
+  })
+
+  test('a refused release writes nothing', () => {
+    const east = mezzanineEdgeHandles(nodes(), mezzanineId).find(
+      (handle) => handle.outward[0] > 0.9,
+    )!
+    let at = 0
+    runMezzanineEdgeDrag({
+      handle: east,
+      zoneId: mezzanineId,
+      levelId: LEVEL,
+      from: 0,
+      along: () => at,
+    })
+    at = 10
+    window.dispatchEvent(Object.assign(new Event('pointermove'), { clientX: 1, clientY: 1 }))
+    window.dispatchEvent(Object.assign(new Event('pointerup'), { clientX: 1, clientY: 1 }))
+    expect(bounds(zone(mezzanineId).polygon)[2]).toBeCloseTo(4)
+    expect(history()).toBe(0)
+  })
+})
+
+describe('adding stairs', () => {
+  test('places one stair up to the mezzanine and selects it, in one step', () => {
+    const result = addMezzanineStairs(mezzanineId)
+    expect(result.ok).toBe(true)
+    const stairId = (result as { stairId: string }).stairId
+    expect(nodes()[stairId as AnyNodeId]?.type).toBe('stair')
+    expect(useViewer.getState().selection.selectedIds).toEqual([stairId])
+    expect(useEditor.getState().room).toBeNull()
+    expect(history()).toBe(1)
+    // The railing opens where the flight arrives, in the same step.
+    const deck = Object.values(nodes()).find(
+      (node) => node.type === 'slab' && node.support === 'open',
+    ) as { railing?: unknown[] }
+    expect(deck.railing).toHaveLength(5)
+    // Core emits the same numeric values that shared history records through JSON.
+    const hasNegativeZero = (value: unknown): boolean =>
+      Object.is(value, -0) ||
+      (Array.isArray(value)
+        ? value.some(hasNegativeZero)
+        : !!value && typeof value === 'object' && Object.values(value).some(hasNegativeZero))
+    const stair = nodes()[stairId as AnyNodeId]!
+    expect(hasNegativeZero(stair)).toBe(false)
+    expect(
+      Object.values(nodes()).some((node) => node.parentId === stairId && hasNegativeZero(node)),
+    ).toBe(false)
+    // One ⌘Z takes it away again.
+    expect(runHistoryShortcut('undo')).toBe(true)
+    expect(nodes()[stairId as AnyNodeId]).toBeUndefined()
+    expect(Object.values(nodes()).some((node) => node.type === 'stair')).toBe(false)
+  })
+
+  test('says "No room for stairs" when no edge has free floor for a flight', () => {
+    // The mezzanine fills the room: no host floor is left for a flight.
+    useScene.getState().updateNode(
+      mezzanineId as AnyNodeId,
+      {
+        polygon: [
+          [0.2, 0.2],
+          [7.8, 0.2],
+          [7.8, 5.8],
+          [0.2, 5.8],
+        ],
+      } as never,
+    )
+    clearSceneHistory()
+    const result = addMezzanineStairs(mezzanineId)
+    expect(result).toEqual({ ok: false, message: MEZZANINE_NO_STAIR_MESSAGE })
+    expect(Object.values(nodes()).some((node) => node.type === 'stair')).toBe(false)
+    expect(history()).toBe(0)
+  })
+})