@pascal-app/editor 1.0.3 → 1.0.4

package/src/lib/wall-region-face.ts

@@ -0,0 +1,352 @@
+import {
+  type AnyNode,
+  getWallArcData,
+  getWallCurveFrameAt,
+  getWallFaceAtLocalPoint,
+  getWallFaceOffsets,
+  isCurvedWall,
+  resolveLevelId,
+  spatialGridManager,
+  type WallFace,
+  type WallNode,
+  type WallSlabSupportSegment,
+} from '@pascal-app/core'
+import { getWallFinishData } from '@pascal-app/viewer'
+import type { BufferGeometry } from 'three'
+import { faceBaseAt, type WallFaceBaseRuns } from './wall-region-snap'
+
+// Face geometry for the paint tool's wall regions, all in the wall mesh's local
+// frame (x along the chord from the start, y up from the slab the mesh stands
+// on, z toward the chord's left). A region's `u` is that local x, on straight
+// and curved walls alike; its `v` is local y above the face's own base.
+
+type WallShape = Pick<
+  WallNode,
+  'start' | 'end' | 'thickness' | 'justification' | 'curveOffset' | 'height'
+>
+
+export type WallFaceFrame = {
+  face: WallFace
+  length: number
+  /** Straight wall: the face plane's local z. */
+  z: number
+  /** Curved wall: the face's circle in local xz and the side of its centre the face lies on. */
+  arc: { cx: number; cz: number; radius: number; side: number } | null
+}
+
+export type WallFaceExtent = {
+  /** Local x range the face covers (mitred ends reach past 0 and the length). */
+  uMin: number
+  uMax: number
+  /** Local y of the face top. */
+  top: number
+}
+
+type FaceBase = Record<WallFace, WallFaceBaseRuns> | null
+
+function chordFrame(wall: Pick<WallNode, 'start' | 'end'>) {
+  const dx = wall.end[0] - wall.start[0]
+  const dz = wall.end[1] - wall.start[1]
+  const length = Math.hypot(dx, dz)
+  const tx = length > 1e-9 ? dx / length : 1
+  const tz = length > 1e-9 ? dz / length : 0
+  const toLocal = (x: number, z: number): [number, number] => {
+    const ox = x - wall.start[0]
+    const oz = z - wall.start[1]
+    return [ox * tx + oz * tz, -ox * tz + oz * tx]
+  }
+  return { length, toLocal }
+}
+
+export function wallFaceFrame(wall: WallShape, face: WallFace): WallFaceFrame {
+  const { length, toLocal } = chordFrame(wall)
+  const offset = getWallFaceOffsets(wall)[face]
+  const arc = isCurvedWall(wall) ? getWallArcData(wall) : null
+  if (!arc) return { face, length, z: offset, arc: null }
+  const [cx, cz] = toLocal(arc.center.x, arc.center.y)
+  const mid = getWallCurveFrameAt(wall, 0.5).point
+  const [, midZ] = toLocal(mid.x, mid.y)
+  // Left of a counter-clockwise arc points at its centre (`getWallFaceAtLocalPoint`).
+  const radius = arc.direction > 0 ? arc.radius - offset : arc.radius + offset
+  return { face, length, z: offset, arc: { cx, cz, radius, side: midZ >= cz ? 1 : -1 } }
+}
+
+/** Local (x, z) of the face surface at station `u`. */
+export function faceSurfaceXZ(frame: WallFaceFrame, u: number): [number, number] {
+  const { arc } = frame
+  if (!arc) return [u, frame.z]
+  const dx = u - arc.cx
+  return [u, arc.cz + arc.side * Math.sqrt(Math.max(0, arc.radius * arc.radius - dx * dx))]
+}
+
+/** Unit local xz normal pointing out of the face at station `u`. */
+export function faceOutwardXZ(
+  frame: WallFaceFrame,
+  other: WallFaceFrame,
+  u: number,
+): [number, number] {
+  const [x, z] = faceSurfaceXZ(frame, u)
+  const [ox, oz] = faceSurfaceXZ(other, u)
+  const length = Math.hypot(x - ox, z - oz)
+  if (length < 1e-9) return [0, frame.face === 'a' ? 1 : -1]
+  return [(x - ox) / length, (z - oz) / length]
+}
+
+/**
+ * Where a local ray meets the face surface (infinite plane or cylinder), as
+ * local (u, y). Null when the ray runs parallel or points away.
+ */
+export function projectLocalRayToFace(
+  frame: WallFaceFrame,
+  origin: readonly [number, number, number],
+  direction: readonly [number, number, number],
+): { u: number; y: number } | null {
+  const [ox, oy, oz] = origin
+  const [dx, dy, dz] = direction
+  if (!frame.arc) {
+    if (Math.abs(dz) < 1e-9) return null
+    const t = (frame.z - oz) / dz
+    return t > 0 ? { u: ox + dx * t, y: oy + dy * t } : null
+  }
+  const { cx, cz, radius, side } = frame.arc
+  const px = ox - cx
+  const pz = oz - cz
+  const a = dx * dx + dz * dz
+  if (a < 1e-12) return null
+  const b = 2 * (px * dx + pz * dz)
+  const c = px * px + pz * pz - radius * radius
+  const disc = b * b - 4 * a * c
+  if (disc < 0) return null
+  const root = Math.sqrt(disc)
+  for (const t of [(-b - root) / (2 * a), (-b + root) / (2 * a)]) {
+    if (t <= 0) continue
+    // The circle's far half is not this face.
+    if ((oz + dz * t - cz) * side < 0) continue
+    return { u: ox + dx * t, y: oy + dy * t }
+  }
+  return null
+}
+
+/**
+ * Face and (u, v) of a hit on the wall mesh, by the same rule as the paint
+ * resolver (`resolveWallRole`): face from where the point lies, u = local x,
+ * v = local y above that face's base at u.
+ */
+export function wallHitFaceUV(
+  wall: Pick<WallNode, 'start' | 'end' | 'thickness' | 'justification' | 'curveOffset'>,
+  localPosition: readonly [number, number, number],
+  localNormal: readonly [number, number, number] | undefined,
+  faceBase: FaceBase,
+): { face: WallFace; u: number; v: number } | null {
+  const face = getWallFaceAtLocalPoint(wall, localPosition, localNormal)
+  if (!face) return null
+  const u = localPosition[0]
+  return { face, u, v: localPosition[1] - faceBaseAt(faceBase?.[face] ?? null, u) }
+}
+
+/** Local x of a support-segment parameter, as the wall renderer measures it. */
+function stationX(wall: WallShape, t: number, length: number): number {
+  if (!isCurvedWall(wall)) return t * length
+  const point = getWallCurveFrameAt(wall, t).point
+  const dx = wall.end[0] - wall.start[0]
+  const dz = wall.end[1] - wall.start[1]
+  return ((point.x - wall.start[0]) * dx + (point.y - wall.start[1]) * dz) / length
+}
+
+/**
+ * Each face's base runs as the renderer measures region heights. A built wall
+ * that carries finishes stores them on its geometry; a plain wall does not, so
+ * they are derived the way its first region's rebuild will derive them — a
+ * region drawn on a stepped face lands where it was drawn.
+ */
+export function resolveWallFaceBase(
+  wall: WallNode,
+  geometry: BufferGeometry | undefined | null,
+  nodes: Readonly<Record<string, AnyNode | undefined>>,
+): FaceBase {
+  const data = getWallFinishData(geometry)
+  if (data) return data.faceBase
+  const cached = derivedFaceBase.get(wall)
+  if (cached?.nodes === nodes) return cached.faceBase
+  const faceBase = deriveWallFaceBase(wall, nodes)
+  derivedFaceBase.set(wall, { nodes, faceBase })
+  return faceBase
+}
+
+// The derivation runs the slab-support election, so a hovering pointer reuses
+// it until the wall or the scene changes.
+const derivedFaceBase = new WeakMap<
+  WallNode,
+  { nodes: Readonly<Record<string, AnyNode | undefined>>; faceBase: FaceBase }
+>()
+
+function deriveWallFaceBase(
+  wall: WallNode,
+  nodes: Readonly<Record<string, AnyNode | undefined>>,
+): FaceBase {
+  const support = spatialGridManager.getSlabSupportForWall(
+    resolveLevelId(wall, nodes as Record<string, AnyNode>),
+    wall.start,
+    wall.end,
+    wall.curveOffset ?? 0,
+    wall.thickness,
+    wall.supportSlabId,
+    undefined,
+    wall.supportOffset,
+    wall.justification,
+  )
+  const faceBase = support.faceDatum
+  if (!faceBase) return null
+  const same = [faceBase.a, faceBase.b].every(
+    (segments) => JSON.stringify(segments) === JSON.stringify(support.baseSegments),
+  )
+  if (same) return null
+  const { length } = chordFrame(wall)
+  const runs = (segments: readonly WallSlabSupportSegment[]) =>
+    segments
+      .map((segment) => ({
+        start: stationX(wall, segment.start, length),
+        end: stationX(wall, segment.end, length),
+        y: segment.elevation - support.elevation,
+      }))
+      .sort((left, right) => left.start - right.start)
+  return { a: runs(faceBase.a), b: runs(faceBase.b) }
+}
+
+const extentCache = new WeakMap<BufferGeometry, Map<string, WallFaceExtent>>()
+
+/** The face's local x range and top, read off the built geometry. */
+export function wallFaceExtent(
+  wall: WallShape,
+  face: WallFace,
+  geometry: BufferGeometry | undefined | null,
+): WallFaceExtent {
+  const frame = wallFaceFrame(wall, face)
+  const fallback = { uMin: 0, uMax: frame.length, top: wall.height ?? 2.5 }
+  const position = geometry?.getAttribute('position')
+  if (!(geometry && position)) return fallback
+  const key = `${face}:${frame.z}:${frame.arc?.radius ?? ''}`
+  const cached = extentCache.get(geometry)?.get(key)
+  if (cached) return cached
+  let uMin = Number.POSITIVE_INFINITY
+  let uMax = Number.NEGATIVE_INFINITY
+  let top = Number.NEGATIVE_INFINITY
+  for (let index = 0; index < position.count; index++) {
+    const x = position.getX(index)
+    const z = position.getZ(index)
+    const off = frame.arc
+      ? Math.abs(Math.hypot(x - frame.arc.cx, z - frame.arc.cz) - frame.arc.radius)
+      : Math.abs(z - frame.z)
+    if (off > 3e-3) continue
+    uMin = Math.min(uMin, x)
+    uMax = Math.max(uMax, x)
+    top = Math.max(top, position.getY(index))
+  }
+  const extent = Number.isFinite(top) && uMax > uMin ? { uMin, uMax, top } : fallback
+  const perGeometry = extentCache.get(geometry) ?? new Map<string, WallFaceExtent>()
+  perGeometry.set(key, extent)
+  extentCache.set(geometry, perGeometry)
+  return extent
+}
+
+/** A span of the face in region terms: absent bounds run to the face's edges. */
+export type FaceSpan = { u0?: number; u1?: number; v0?: number; v1?: number }
+
+type FaceStrip = { u0: number; u1: number; low: number; high: number }
+
+/**
+ * The span cut into pieces that each stand on one base run (and, on a curved
+ * wall, short enough to follow the arc), with local y bottom and top.
+ */
+export function faceSpanStrips(
+  frame: WallFaceFrame,
+  extent: WallFaceExtent,
+  runs: WallFaceBaseRuns,
+  span: FaceSpan,
+): FaceStrip[] {
+  const start = Math.max(span.u0 ?? extent.uMin, extent.uMin)
+  const end = Math.min(span.u1 ?? extent.uMax, extent.uMax)
+  if (end - start < 1e-6) return []
+  const stations = [start, end]
+  for (const run of runs ?? [])
+    for (const edge of [run.start, run.end]) if (edge > start && edge < end) stations.push(edge)
+  if (frame.arc) {
+    const pieces = Math.max(1, Math.ceil((end - start) / 0.1))
+    for (let index = 1; index < pieces; index++)
+      stations.push(start + ((end - start) * index) / pieces)
+  }
+  stations.sort((a, b) => a - b)
+  const strips: FaceStrip[] = []
+  for (let index = 0; index < stations.length - 1; index++) {
+    const u0 = stations[index]!
+    const u1 = stations[index + 1]!
+    if (u1 - u0 < 1e-6) continue
+    const base = faceBaseAt(runs, (u0 + u1) / 2)
+    const low = Math.max(base + (span.v0 ?? 0), base)
+    const high = Math.min(span.v1 === undefined ? extent.top : base + span.v1, extent.top)
+    if (high - low > 1e-6) strips.push({ u0, u1, low, high })
+  }
+  return strips
+}
+
+function lift(frame: WallFaceFrame, other: WallFaceFrame, u: number, offset: number) {
+  const [x, z] = faceSurfaceXZ(frame, u)
+  const [nx, nz] = faceOutwardXZ(frame, other, u)
+  return [x + nx * offset, z + nz * offset] as const
+}
+
+/** Triangles covering the strips, lifted `offset` metres off the face. */
+export function faceStripTriangles(
+  frame: WallFaceFrame,
+  other: WallFaceFrame,
+  strips: readonly FaceStrip[],
+  offset: number,
+): Float32Array {
+  const out: number[] = []
+  for (const { u0, u1, low, high } of strips) {
+    const [ax, az] = lift(frame, other, u0, offset)
+    const [bx, bz] = lift(frame, other, u1, offset)
+    out.push(ax, low, az, bx, low, bz, bx, high, bz, ax, low, az, bx, high, bz, ax, high, az)
+  }
+  return new Float32Array(out)
+}
+
+/** Line segments around the strips' outline (steps included), lifted off the face. */
+export function faceStripOutline(
+  frame: WallFaceFrame,
+  other: WallFaceFrame,
+  strips: readonly FaceStrip[],
+  offset: number,
+): Float32Array {
+  const out: number[] = []
+  strips.forEach((strip, index) => {
+    const [ax, az] = lift(frame, other, strip.u0, offset)
+    const [bx, bz] = lift(frame, other, strip.u1, offset)
+    out.push(ax, strip.low, az, bx, strip.low, bz, ax, strip.high, az, bx, strip.high, bz)
+    const previous = strips[index - 1]
+    if (!previous || Math.abs(previous.u1 - strip.u0) > 1e-6) {
+      out.push(ax, strip.low, az, ax, strip.high, az)
+    } else {
+      if (Math.abs(previous.low - strip.low) > 1e-6)
+        out.push(ax, previous.low, az, ax, strip.low, az)
+      if (Math.abs(previous.high - strip.high) > 1e-6)
+        out.push(ax, previous.high, az, ax, strip.high, az)
+    }
+    const next = strips[index + 1]
+    if (!next || Math.abs(next.u0 - strip.u1) > 1e-6)
+      out.push(bx, strip.low, bz, bx, strip.high, bz)
+  })
+  return new Float32Array(out)
+}
+
+/** Local position of face point (u, local y), lifted `offset` metres off the face. */
+export function facePoint(
+  frame: WallFaceFrame,
+  other: WallFaceFrame,
+  u: number,
+  y: number,
+  offset: number,
+): [number, number, number] {
+  const [x, z] = lift(frame, other, u, offset)
+  return [x, y, z]
+}

package/src/lib/wall-region-handles.test.ts

@@ -0,0 +1,304 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import {
+  type AnyNodeId,
+  getWallCurveFrameAt,
+  getWallFaceOffsets,
+  runAsSingleSceneHistoryStep,
+  useLiveNodeOverrides,
+  useScene,
+  type WallFaceRegion,
+  WallNode,
+} from '@pascal-app/core'
+import { Matrix4, Ray, Vector3 } from 'three'
+import { commitHandleDragPatch } from '../components/editor/handles/handle-drag-history'
+import { updateWallRegion } from './paint-regions'
+import {
+  buildOutlineRibbon,
+  faceSurfacePoint,
+  getWallFaceSurface,
+  intersectFaceSurface,
+  REGION_MIN_SIZE,
+  regionHandlePlacements,
+  regionOutline,
+  resolveRegionBoundDrag,
+  wallLocalMatrix,
+  withRegionBounds,
+} from './wall-region-handles'
+import { wallRegionSnapTargets } from './wall-region-snap'
+
+type RafFn = (callback: (time: number) => void) => number
+;(globalThis as { requestAnimationFrame?: RafFn }).requestAnimationFrame ??= (callback) => {
+  callback(0)
+  return 0
+}
+;(globalThis as { cancelAnimationFrame?: (id: number) => void }).cancelAnimationFrame ??= () => {}
+
+const straight = WallNode.parse({ start: [0, 0], end: [4, 0], thickness: 0.2 })
+const curved = WallNode.parse({ start: [0, 0], end: [4, 0], thickness: 0.2, curveOffset: 0.8 })
+const curvedBack = WallNode.parse({
+  start: [0, 0],
+  end: [4, 0],
+  thickness: 0.2,
+  curveOffset: -0.8,
+})
+const flat = () => 0
+
+/** A ray that starts `distance` out from the face point at (u, y) and aims back at it. */
+function rayAt(surface: ReturnType<typeof getWallFaceSurface>, u: number, y: number, distance = 3) {
+  const point = faceSurfacePoint(surface, u)
+  const origin = {
+    x: point.x + point.nx * distance + 0.4,
+    y: y + 0.7,
+    z: point.z + point.nz * distance,
+  }
+  return {
+    origin,
+    direction: { x: point.x - origin.x, y: y - origin.y, z: point.z - origin.z },
+  }
+}
+
+describe('wall face surface', () => {
+  test('a straight face sits at its offset with an outward normal', () => {
+    const offsets = getWallFaceOffsets(straight)
+    const a = faceSurfacePoint(getWallFaceSurface(straight, 'a'), 1.5)
+    const b = faceSurfacePoint(getWallFaceSurface(straight, 'b'), 1.5)
+    expect(a).toEqual({ x: 1.5, z: offsets.a, nx: 0, nz: 1, tx: 1, tz: 0 })
+    expect(b.z).toBe(offsets.b)
+    expect(b.nz).toBe(-1)
+  })
+
+  for (const [label, wall] of [
+    ['bulging right', curved],
+    ['bulging left', curvedBack],
+  ] as const) {
+    test(`a curved face (${label}) follows the arc offset by the face offset`, () => {
+      const offsets = getWallFaceOffsets(wall)
+      for (const face of ['a', 'b'] as const) {
+        const surface = getWallFaceSurface(wall, face)
+        for (const t of [0.2, 0.5, 0.8]) {
+          const frame = getWallCurveFrameAt(wall, t)
+          const expected = {
+            x: frame.point.x + frame.normal.x * offsets[face],
+            z: frame.point.y + frame.normal.y * offsets[face],
+          }
+          const point = faceSurfacePoint(surface, expected.x)
+          expect(point.z).toBeCloseTo(expected.z, 6)
+          const outward = face === 'a' ? 1 : -1
+          expect(point.nx).toBeCloseTo(frame.normal.x * outward, 6)
+          expect(point.nz).toBeCloseTo(frame.normal.y * outward, 6)
+          expect(point.tx).toBeCloseTo(frame.tangent.x, 6)
+          expect(point.tz).toBeCloseTo(frame.tangent.y, 6)
+        }
+      }
+    })
+  }
+})
+
+describe('pointer on the face', () => {
+  for (const [label, wall] of [
+    ['straight', straight],
+    ['curved', curved],
+    ['curved the other way', curvedBack],
+  ] as const) {
+    test(`recovers u and y on a ${label} wall, both faces`, () => {
+      for (const face of ['a', 'b'] as const) {
+        const surface = getWallFaceSurface(wall, face)
+        for (const [u, y] of [
+          [0.4, 0.3],
+          [2, 1.2],
+          [3.5, 2.1],
+        ] as const) {
+          const { origin, direction } = rayAt(surface, u, y)
+          const hit = intersectFaceSurface(surface, origin, direction)
+          expect(hit?.u).toBeCloseTo(u, 6)
+          expect(hit?.y).toBeCloseTo(y, 6)
+        }
+      }
+    })
+  }
+
+  test('misses a ray running parallel to a straight face or pointing away', () => {
+    const surface = getWallFaceSurface(straight, 'a')
+    expect(intersectFaceSurface(surface, { x: 0, y: 1, z: 2 }, { x: 1, y: 0, z: 0 })).toBeNull()
+    expect(intersectFaceSurface(surface, { x: 0, y: 1, z: 2 }, { x: 0, y: 0, z: 1 })).toBeNull()
+  })
+
+  test('a world ray maps through the wall-local frame of a rotated wall', () => {
+    const wall = WallNode.parse({ start: [1, 2], end: [1, 6], thickness: 0.2 })
+    const level = new Matrix4().makeTranslation(10, 3, -4)
+    const local = wallLocalMatrix(wall, 0.25)
+    const toWorld = level.clone().multiply(local)
+    const surface = getWallFaceSurface(wall, 'b')
+    const { origin, direction } = rayAt(surface, 2.5, 1.1)
+    const worldOrigin = new Vector3(origin.x, origin.y, origin.z).applyMatrix4(toWorld)
+    const worldTarget = new Vector3(
+      origin.x + direction.x,
+      origin.y + direction.y,
+      origin.z + direction.z,
+    ).applyMatrix4(toWorld)
+    const ray = new Ray(worldOrigin, worldTarget.clone().sub(worldOrigin).normalize())
+    ray.applyMatrix4(toWorld.clone().invert())
+    const hit = intersectFaceSurface(surface, ray.origin, ray.direction)
+    expect(hit?.u).toBeCloseTo(2.5, 6)
+    expect(hit?.y).toBeCloseTo(1.1, 6)
+  })
+})
+
+describe('bound drag', () => {
+  const region: WallFaceRegion = { id: 'r1', face: 'a', u0: 1, u1: 2, v1: 0.9, finish: 'x' }
+  const drag = (edge: 'u0' | 'u1' | 'v0' | 'v1', raw: number, extra = {}) =>
+    resolveRegionBoundDrag({ region, edge, raw, length: 4, faceHeight: 2.5, ...extra })
+
+  test('moves only the dragged bound', () => {
+    expect(drag('v1', 1.234)).toEqual({ u0: 1, u1: 2, v1: 1.234 })
+    expect(drag('u0', 0.5)).toEqual({ u0: 0.5, u1: 2, v1: 0.9 })
+  })
+
+  test('snaps to the grid step', () => {
+    expect(drag('v1', 1.234, { gridStep: 0.1 }).v1).toBeCloseTo(1.2, 9)
+    expect(drag('u1', 2.63, { gridStep: 0.25 }).u1).toBeCloseTo(2.75, 9)
+  })
+
+  test('keeps the minimum size against the opposite bound', () => {
+    expect(drag('u0', 1.995).u0).toBeCloseTo(2 - REGION_MIN_SIZE, 9)
+    expect(drag('u1', 0.2).u1).toBeCloseTo(1 + REGION_MIN_SIZE, 9)
+    expect(drag('v1', -1).v1).toBeCloseTo(REGION_MIN_SIZE, 9)
+  })
+
+  test('a bound dragged onto or past the face edge becomes absent', () => {
+    expect(drag('v1', 3)).toEqual({ u0: 1, u1: 2 })
+    expect(drag('u0', -0.5)).toEqual({ u1: 2, v1: 0.9 })
+    expect(drag('u1', 4)).toEqual({ u0: 1, v1: 0.9 })
+  })
+
+  test('an absent bound starts from the face edge when dragged in', () => {
+    expect(drag('v0', 0.3)).toEqual({ u0: 1, u1: 2, v0: 0.3, v1: 0.9 })
+    expect(drag('v0', 0.95).v0).toBeCloseTo(0.9 - REGION_MIN_SIZE, 9)
+  })
+
+  test('edge snapping pulls to other regions and the face edges, over the grid', () => {
+    const others: WallFaceRegion[] = [
+      region,
+      { id: 'r2', face: 'a', u0: 2.47, finish: 'y' },
+      { id: 'r3', face: 'b', u0: 2.6, finish: 'z' },
+    ]
+    const wall = { start: [0, 0], end: [4, 0], children: [], faceRegions: others } as never
+    const snapTargets = wallRegionSnapTargets(wall, 'a', {}, null, { excludeRegionId: 'r1' }).u
+    expect(snapTargets).toEqual([0, 2.47, 4])
+    expect(drag('u1', 2.52, { gridStep: 0.1, edgeSnap: true, snapTargets }).u1).toBe(2.47)
+    expect(drag('u1', 2.52, { gridStep: 0.1, snapTargets }).u1).toBeCloseTo(2.5, 9)
+    expect(drag('v0', 0.05, { edgeSnap: true })).toEqual({ u0: 1, u1: 2, v1: 0.9 })
+  })
+
+  test('withRegionBounds replaces one region and keeps the rest', () => {
+    const regions: WallFaceRegion[] = [region, { id: 'r2', face: 'b', v0: 1, finish: 'y' }]
+    expect(withRegionBounds(regions, 'r1', { u0: 0.5 })).toEqual([
+      { id: 'r1', face: 'a', u0: 0.5, finish: 'x' },
+      regions[1]!,
+    ])
+  })
+})
+
+describe('handles and outline', () => {
+  test('one handle per bounded edge, at mid-height / mid-width on the face', () => {
+    const surface = getWallFaceSurface(straight, 'a')
+    const placements = regionHandlePlacements(
+      surface,
+      { id: 'r', face: 'a', u0: 1, u1: 3, v1: 0.9, finish: 'x' },
+      2.5,
+      flat,
+      null,
+      0,
+    )
+    expect(placements.map((p) => p.edge)).toEqual(['u0', 'u1', 'v1'])
+    expect(placements[0]!.position).toEqual([1, 0.45, 0.1])
+    expect(placements[2]!.position).toEqual([2, 0.9, 0.1])
+    expect(placements[2]!.tipAngle).toBeCloseTo(Math.PI / 2, 9)
+  })
+
+  test('a dragged edge keeps its handle after it goes absent', () => {
+    const surface = getWallFaceSurface(straight, 'b')
+    const region: WallFaceRegion = { id: 'r', face: 'b', u0: 1, finish: 'x' }
+    expect(regionHandlePlacements(surface, region, 2.5, flat).map((p) => p.edge)).toEqual(['u0'])
+    expect(regionHandlePlacements(surface, region, 2.5, flat, 'v1').map((p) => p.edge)).toEqual([
+      'u0',
+      'v1',
+    ])
+  })
+
+  test('v follows the face base', () => {
+    const surface = getWallFaceSurface(straight, 'a')
+    const [handle] = regionHandlePlacements(
+      surface,
+      { id: 'r', face: 'a', v1: 1, finish: 'x' },
+      2.5,
+      () => -0.3,
+    )
+    expect(handle!.position[1]).toBeCloseTo(0.7, 9)
+  })
+
+  test('the outline of a curved region hugs the face', () => {
+    const surface = getWallFaceSurface(curved, 'a')
+    const outline = regionOutline(surface, { id: 'r', face: 'a', v1: 1, finish: 'x' }, 2.5, flat, 0)
+    expect(outline.length).toBeGreaterThan(4)
+    for (const point of outline) {
+      expect(point.position[2]).toBeCloseTo(faceSurfacePoint(surface, point.position[0]).z, 6)
+    }
+    const ribbon = buildOutlineRibbon(outline, 0.01)
+    expect(ribbon.length).toBe(outline.length * 6 * 3)
+  })
+})
+
+describe('commit', () => {
+  const WALL_ID = 'wall_region-handles-commit' as AnyNodeId
+  const wall = () => useScene.getState().nodes[WALL_ID] as WallNode
+
+  beforeEach(() => {
+    useScene.setState({ nodes: {}, rootNodeIds: [], dirtyNodes: new Set() } as never)
+    useScene.getState().createNode(
+      WallNode.parse({
+        id: WALL_ID,
+        start: [0, 0],
+        end: [4, 0],
+        faceRegions: [
+          { id: 'r1', face: 'a', v1: 0.9, finish: 'library:paint-white' },
+          { id: 'r2', face: 'b', u0: 1, u1: 2, finish: 'library:paint-white' },
+        ],
+      }),
+    )
+    useScene.temporal.getState().clear()
+    useScene.temporal.getState().resume()
+  })
+
+  test('a drag previews live and commits as one undo step', () => {
+    const regions = wall().faceRegions!
+    useScene.temporal.getState().pause()
+    const bounds = resolveRegionBoundDrag({
+      region: regions[0]!,
+      edge: 'v1',
+      raw: 1.2,
+      length: 4,
+      faceHeight: 2.5,
+    })
+    useLiveNodeOverrides
+      .getState()
+      .set(WALL_ID, { faceRegions: withRegionBounds(regions, 'r1', bounds) })
+    expect(wall().faceRegions![0]!.v1).toBe(0.9)
+
+    commitHandleDragPatch({
+      patch: bounds,
+      resumeHistory: () => useScene.temporal.getState().resume(),
+      runAsSingleHistoryStep: (run) => runAsSingleSceneHistoryStep(useScene, run),
+      commit: (next) => updateWallRegion(WALL_ID, 'r1', next),
+    })
+    useLiveNodeOverrides.getState().clear(WALL_ID)
+
+    expect(useScene.temporal.getState().pastStates).toHaveLength(1)
+    expect(wall().faceRegions).toEqual([
+      { id: 'r1', face: 'a', v1: 1.2, finish: 'library:paint-white' },
+      regions[1]!,
+    ])
+    useScene.temporal.getState().undo()
+    expect(wall().faceRegions![0]!.v1).toBe(0.9)
+  })
+})