@pascal-app/editor 1.0.3 → 1.0.5

package/src/components/systems/zone/zone-system.test.ts

@@ -0,0 +1,47 @@
+import { expect, test } from 'bun:test'
+import { useScene, ZoneNode } from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { act, create } from '@react-three/test-renderer'
+import { createElement } from 'react'
+import useEditor from '../../../store/use-editor'
+import { ZoneSystem } from './zone-system'
+
+test('zone volumes mount only while a unit is painted, never for a selected zone', async () => {
+  const previousScene = useScene.getState()
+  const previousViewer = useViewer.getState()
+  const previousEditor = useEditor.getState()
+  const zone = ZoneNode.parse({
+    name: 'Courtyard',
+    polygon: [
+      [0, 0],
+      [4, 0],
+      [4, 4],
+      [0, 4],
+    ],
+  })
+  useScene.setState({ nodes: { [zone.id]: zone } })
+  useViewer.setState({
+    focusedUnitId: null,
+    showZones: false,
+    selection: { buildingId: null, levelId: null, zoneId: null, selectedIds: [zone.id] },
+  })
+  useEditor.setState({ isCaptureMode: false })
+  const renderer = await create(createElement(ZoneSystem))
+  try {
+    // A selected drawn zone looks like a room: outline, no tinted volume.
+    expect(useViewer.getState().showZones).toBe(false)
+    await act(async () => useViewer.setState({ focusedUnitId: 'unit_paint' as never }))
+    expect(useViewer.getState().showZones).toBe(true)
+    await act(async () => useEditor.getState().setCaptureMode(true))
+    expect(useViewer.getState().showZones).toBe(false)
+    await act(async () => useEditor.getState().setCaptureMode(false))
+    expect(useViewer.getState().showZones).toBe(true)
+    await act(async () => useViewer.setState({ focusedUnitId: null }))
+    expect(useViewer.getState().showZones).toBe(false)
+  } finally {
+    await renderer.unmount()
+    useScene.setState(previousScene)
+    useViewer.setState(previousViewer)
+    useEditor.setState(previousEditor)
+  }
+})

package/src/components/systems/zone/zone-system.tsx

@@ -9,40 +9,32 @@ import useEditor from '../../../store/use-editor'
 import useInteractionScope from '../../../store/use-interaction-scope'
 
 // Disable raycasting on zone geometry so clicks pass through to items underneath.
-// Zone selection in the editor is handled exclusively via the HTML label overlay.
 const noopRaycast = () => {}
 
+/**
+ * Zone volumes are a working view for one job only: painting a unit's
+ * membership, where every zone on the level has to be in view. Otherwise every
+ * zone, drawn or detected, shows as a room: a light label pill (`RoomLabels3D`)
+ * and the room outline when selected. Mounting is the viewer's `showZones`
+ * flag: unmounting skips the meshes and drei labels entirely, and the cleanup
+ * restores the default so preview / first-person surfaces keep their labels.
+ */
 export const ZoneSystem = () => {
-  // Outside the zones layer (or during snapshot capture) zones unmount
-  // entirely — meshes AND drei <Html> labels, which cost per-frame matrix work
-  // + live DOM even at opacity 0. The renderer reads this viewer flag; the
-  // unmount cleanup restores the default so preview / first-person surfaces
-  // (which swap this system for ViewerZoneSystem) keep their labels.
-  const structureLayerState = useEditor((s) => s.structureLayer)
-  const isCaptureModeState = useEditor((s) => s.isCaptureMode)
+  const focusedUnitId = useViewer((s) => s.focusedUnitId)
+  const isCaptureMode = useEditor((s) => s.isCaptureMode)
+  const active = !!focusedUnitId && !isCaptureMode
   useEffect(() => {
-    useViewer.getState().setShowZones(structureLayerState === 'zones' && !isCaptureModeState)
+    useViewer.getState().setShowZones(active)
     return () => useViewer.getState().setShowZones(true)
-  }, [structureLayerState, isCaptureModeState])
+  }, [active])
 
   useFrame((_, delta) => {
     if (!useViewer.getState().showZones) return
 
-    const structureLayer = useEditor.getState().structureLayer
-    const editorMode = useEditor.getState().mode
-    const selectedLevelId = useViewer.getState().selection.levelId
-    const selectedZoneId = useViewer.getState().selection.zoneId
-    const hoveredId = useViewer.getState().hoveredId
-    // Snapshot capture is a clean, camera-only surface — never show zone
-    // geometry or the HTML zone tags in the framed shot.
-    const isCaptureMode = useEditor.getState().isCaptureMode
-
-    // During any active interaction zone labels step back entirely — they are
-    // not a primary editing concern and would distract / invite misclicks.
+    const { levelId: selectedLevelId } = useViewer.getState().selection
+    // During any active interaction zone labels step back entirely.
     const zoneLabelsHidden =
       resolveOverlayPolicy(useInteractionScope.getState().scope).zoneLabels === 'hidden'
-
-    const zoneGeometryVisible = structureLayer === 'zones'
     const zones = sceneRegistry.byType.zone || new Set()
     const nodes = useScene.getState().nodes
     const lerpSpeed = 10 * delta
@@ -52,63 +44,32 @@ export const ZoneSystem = () => {
       if (!obj) return
 
       const zone = nodes[zoneId as ZoneNode['id']] as ZoneNode | undefined
-
       const isOnSelectedLevel = zone?.parentId === selectedLevelId
-      const isSelected = zoneId === selectedZoneId
-      const isDeleteHovered = editorMode === 'delete' && hoveredId === zoneId
-
-      // Keep group visible (so <Html> labels stay active), hide/show meshes only.
-      // Show meshes when: in zone mode, selected, or delete-hovered. A zone the
-      // author hid (sidebar eye) is the one case where the group itself goes:
-      // otherwise this per-frame write would undo the renderer's `visible` prop.
+      // A zone the author hid (sidebar eye) takes its group with it; otherwise
+      // this per-frame write would undo the renderer's `visible` prop.
       const nodeVisible = zone?.visible !== false
       if (obj.visible !== nodeVisible) obj.visible = nodeVisible
-      const meshVisible =
-        nodeVisible && !isCaptureMode && (zoneGeometryVisible || isSelected || isDeleteHovered)
-      const targetOpacity = isCaptureMode
-        ? 0
-        : isSelected || isDeleteHovered
-          ? 1
-          : zoneGeometryVisible
-            ? 1
-            : 0
-
-      // Raycast is re-disabled per frame (not once per group): the meshes
-      // remount whenever the zones layer toggles, so a one-shot flag on the
-      // persistent group would leave fresh meshes clickable.
-      const walls = (obj as Group).getObjectByName('walls') as Mesh | undefined
-      if (walls) {
-        walls.visible = meshVisible
-        walls.raycast = noopRaycast
-        const material = walls.material as MeshBasicNodeMaterial
-        if (material?.userData?.uOpacity) {
-          material.userData.uOpacity.value = MathUtils.lerp(
-            material.userData.uOpacity.value,
-            targetOpacity,
-            lerpSpeed,
-          )
-        }
-      }
+      const shown = nodeVisible && isOnSelectedLevel
 
-      const floor = (obj as Group).getObjectByName('floor') as Mesh | undefined
-      if (floor) {
-        floor.visible = meshVisible
-        floor.raycast = noopRaycast
-        const material = floor.material as MeshBasicNodeMaterial
+      // Raycast is re-disabled per frame: the meshes remount whenever zones
+      // mount again, so a one-shot flag on the persistent group would leave
+      // fresh meshes clickable.
+      for (const name of ['walls', 'floor']) {
+        const mesh = (obj as Group).getObjectByName(name) as Mesh | undefined
+        if (!mesh) continue
+        mesh.visible = shown
+        mesh.raycast = noopRaycast
+        const material = mesh.material as MeshBasicNodeMaterial
         if (material?.userData?.uOpacity) {
           material.userData.uOpacity.value = MathUtils.lerp(
             material.userData.uOpacity.value,
-            targetOpacity,
+            shown ? 1 : 0,
             lerpSpeed,
           )
         }
       }
 
-      // Labels: visible on the current level (regardless of mode), but never
-      // during snapshot capture.
-      const showLabel =
-        nodeVisible && !isCaptureMode && !zoneLabelsHidden && !!selectedLevelId && isOnSelectedLevel
-      const labelOpacity = showLabel ? '1' : '0'
+      const labelOpacity = shown && !zoneLabelsHidden ? '1' : '0'
       const labelEl = document.getElementById(`${zoneId}-label`)
       if (labelEl && labelEl.style.opacity !== labelOpacity) {
         labelEl.style.opacity = labelOpacity

package/src/components/tools/distribution/connection-compatibility.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'bun:test'
+import { connectionCompatibility } from './connection-compatibility'
+
+const supply = { system: 'supply', diameter: 6 }
+test('matching profiles report a match', () => {
+  expect(connectionCompatibility(supply, { ...supply }).status).toBe('match')
+})
+test('system mismatch takes precedence over size', () => {
+  expect(connectionCompatibility(supply, { system: 'return', diameter: 8 }).status).toBe(
+    'incompatible',
+  )
+  expect(
+    connectionCompatibility({ system: 'waste', diameter: 4 }, { system: 'vent', diameter: 4 })
+      .status,
+  ).toBe('incompatible')
+})
+test('size and shape mismatches describe the required adapter', () => {
+  expect(connectionCompatibility(supply, { ...supply, diameter: 8 }).label).toContain('Reducer')
+  expect(
+    connectionCompatibility(supply, { ...supply, shape: 'rect', width: 8, height: 6 }).label,
+  ).toContain('Transition')
+  expect(
+    connectionCompatibility(
+      { ...supply, shape: 'rect', width: 8, height: 6 },
+      { ...supply, shape: 'rect', width: 8, height: 8 },
+    ).status,
+  ).toBe('adapter')
+})
+test('missing system or section data cannot claim compatibility', () => {
+  expect(connectionCompatibility(supply, { diameter: 6 }).status).toBe('unknown')
+  expect(
+    connectionCompatibility({ ...supply, shape: 'rect' }, { ...supply, shape: 'rect' }).status,
+  ).toBe('unknown')
+})

package/src/components/tools/distribution/connection-compatibility.ts

@@ -0,0 +1,43 @@
+import type { NodePort } from '@pascal-app/core'
+
+export type ConnectionProfile = Pick<NodePort, 'system' | 'diameter' | 'shape' | 'width' | 'height'>
+export type ConnectionCompatibility = {
+  status: 'match' | 'adapter' | 'incompatible' | 'unknown'
+  label: string
+}
+
+export function connectionCompatibility(
+  source: ConnectionProfile,
+  target: ConnectionProfile,
+): ConnectionCompatibility {
+  if (source.system && target.system && source.system !== target.system) {
+    return {
+      status: 'incompatible',
+      label: `Different systems: ${source.system} / ${target.system}`,
+    }
+  }
+  const sourceShape = source.shape ?? 'round'
+  const targetShape = target.shape ?? 'round'
+  if (sourceShape !== targetShape) {
+    return { status: 'adapter', label: `Transition needed: ${sourceShape} / ${targetShape}` }
+  }
+  const sourceSize = sourceShape === 'round' ? [source.diameter] : [source.width, source.height]
+  const targetSize = targetShape === 'round' ? [target.diameter] : [target.width, target.height]
+  if (
+    [...sourceSize, ...targetSize].some(
+      (value) => value === undefined || !Number.isFinite(value) || value <= 0,
+    )
+  ) {
+    return { status: 'unknown', label: 'Connection size unavailable' }
+  }
+  if (sourceSize.some((value, index) => Math.abs(value! - targetSize[index]!) > 0.001)) {
+    return {
+      status: 'adapter',
+      label: `Reducer needed: ${sourceSize.join(' × ')}″ / ${targetSize.join(' × ')}″`,
+    }
+  }
+  if (!source.system || !target.system) {
+    return { status: 'unknown', label: 'Size matches; system unspecified' }
+  }
+  return { status: 'match', label: `Matching system and size: ${target.system}` }
+}

package/src/components/tools/distribution/distribution-public.ts

@@ -0,0 +1,9 @@
+export * from './connection-compatibility'
+export * from './distribution-run-contract'
+export * from './distribution-run-tool'
+export * from './draw-alignment'
+export * from './ports'
+export * from './run-cursor'
+export * from './run-direction-feedback'
+export * from './run-port-snap'
+export * from './run-screen-direction'

package/src/components/tools/distribution/distribution-run-contract.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test'
+import { offsetRunPointFromSurface, type RunSurfaceTarget } from './distribution-run-contract'
+
+const wall = (
+  hostId: `wall_${string}` = 'wall_1',
+  side: 'front' | 'back' = 'front',
+): RunSurfaceTarget => ({
+  kind: 'wall',
+  levelId: 'level_1',
+  hostId,
+  side,
+  frame: {
+    origin: [2, 1, 0],
+    normal: [0, 0, 1],
+    tangent: [1, 0, 0],
+    bitangent: [0, 1, 0],
+  },
+  bounds: { minU: 0, maxU: 4, minV: 0, maxV: 2.5 },
+})
+
+describe('distribution run interaction contract', () => {
+  test('offsets wall geometry along the face normal', () => {
+    const target = wall()
+    expect(offsetRunPointFromSurface([3, 1, 0], target, 0.1)).toEqual([3, 1, 0.1])
+  })
+})

package/src/components/tools/distribution/distribution-run-contract.ts

@@ -0,0 +1,94 @@
+import type { AnyNodeId } from '@pascal-app/core'
+
+export type RunPoint = [number, number, number]
+
+export type RunWallSide = 'front' | 'back'
+
+export type RunSurfaceFrame = {
+  origin: RunPoint
+  normal: RunPoint
+  tangent: RunPoint
+  bitangent: RunPoint
+}
+
+export type RunSurfaceBounds = {
+  minU: number
+  maxU: number
+  minV: number
+  maxV: number
+}
+
+export type RunWallAttachment = {
+  wallId: Extract<AnyNodeId, `wall_${string}`>
+  side: RunWallSide
+  startUV: [number, number]
+  endUV: [number, number]
+  offset: number
+}
+
+/**
+ * The surface selected for the current run. A wall target is semantic: the
+ * host id and side are required so later snapping cannot fall back to any
+ * other object that happens to be close in the viewport.
+ */
+export type RunSurfaceTarget =
+  | {
+      kind: 'floor' | 'ceiling' | 'surface'
+      hostId?: AnyNodeId
+      levelId: AnyNodeId
+      frame: RunSurfaceFrame
+    }
+  | {
+      kind: 'wall'
+      levelId: AnyNodeId
+      hostId: AnyNodeId
+      side: RunWallSide
+      frame: RunSurfaceFrame
+      bounds: RunSurfaceBounds
+    }
+
+/** Move a run centerline clear of a wall face along the captured normal. */
+export function offsetRunPointFromSurface(
+  point: RunPoint,
+  target: RunSurfaceTarget | null,
+  offset: number,
+): RunPoint {
+  if (!target || offset === 0) return [...point]
+  return [
+    point[0] + target.frame.normal[0] * offset,
+    point[1] + target.frame.normal[1] * offset,
+    point[2] + target.frame.normal[2] * offset,
+  ]
+}
+
+export function runPointToSurfaceUV(
+  point: RunPoint,
+  target: Extract<RunSurfaceTarget, { kind: 'wall' }>,
+): [number, number] {
+  const dx = point[0] - target.frame.origin[0]
+  const dy = point[1] - target.frame.origin[1]
+  const dz = point[2] - target.frame.origin[2]
+  return [
+    dx * target.frame.tangent[0] + dy * target.frame.tangent[1] + dz * target.frame.tangent[2],
+    dx * target.frame.bitangent[0] +
+      dy * target.frame.bitangent[1] +
+      dz * target.frame.bitangent[2],
+  ]
+}
+
+export function createRunWallAttachment(
+  wallId: Extract<AnyNodeId, `wall_${string}`>,
+  side: RunWallSide,
+  start: RunPoint,
+  end: RunPoint,
+  target: Extract<RunSurfaceTarget, { kind: 'wall' }>,
+  offset: number,
+): RunWallAttachment {
+  return {
+    wallId,
+    side,
+    startUV: runPointToSurfaceUV(start, target),
+    endUV: runPointToSurfaceUV(end, target),
+    offset,
+  }
+}

package/src/components/tools/distribution/distribution-run-tool.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from 'bun:test'
+import { OrthographicCamera, PerspectiveCamera, Raycaster, Vector2, Vector3 } from 'three'
+import {
+  createRunSurfaceFrame,
+  projectRunPointToSurface,
+  projectRunToAngleLock,
+  projectRunToCameraDirection,
+  projectRunToDirection,
+  projectRunToSurfaceAngleLock,
+  type RunCursorRay,
+  type RunPoint,
+  runDistanceSquared,
+  snapRunLength,
+  snapRunPointToSurface,
+  snapRunValue,
+  stepNominalRunSize,
+} from './distribution-run-tool'
+
+describe('distribution run drafting helpers', () => {
+  test('grid length preserves a diagonal from an off-grid socket', () => {
+    const start: RunPoint = [0.13, 0.27, 0.19]
+    const angled = projectRunToAngleLock(start, [1.4, 0.27, 1.3])
+    const point = snapRunLength(start, angled, 0.25)
+    expect(point[0] - start[0]).toBeCloseTo(point[2] - start[2])
+    expect(Math.sqrt(runDistanceSquared(start, point))).toBeCloseTo(1.75)
+    expect(point[1]).toBe(start[1])
+    expect(snapRunLength(start, angled, 0)).toEqual(angled)
+    expect(snapRunLength(start, start, 0.25)).toEqual(start)
+  })
+
+  test('grid length preserves wall-plane diagonals', () => {
+    const start: RunPoint = [0.13, 1.17, 4]
+    const wall = createRunSurfaceFrame(start, [0, 0, 1])
+    const angled = projectRunToSurfaceAngleLock(start, [1.4, 2.3, 4], wall)
+    const point = snapRunLength(start, angled, 0.25)
+    expect(point[0] - start[0]).toBeCloseTo(point[1] - start[1])
+    expect(point[2]).toBe(4)
+    expect(Math.sqrt(runDistanceSquared(start, point))).toBeCloseTo(1.75)
+  })
+
+  test('camera grid snapping steps along a vertical guide from an off-grid origin', () => {
+    const result = projectRunToCameraDirection(
+      [0.13, 0.17, 0.19],
+      { origin: [3.13, 2.3, 3.19], direction: [-Math.SQRT1_2, 0, -Math.SQRT1_2] },
+      [1, 0, 0],
+      0.05,
+      0.25,
+      [[0, 1, 0]],
+    )
+    expect(result?.point[0]).toBe(0.13)
+    expect(result?.point[1]).toBeCloseTo(2.42)
+    expect(result?.point[2]).toBe(0.19)
+  })
+  for (const camera of [
+    new OrthographicCamera(-8, 8, 6, -6, 0.1, 100),
+    new PerspectiveCamera(50, 4 / 3, 0.1, 100),
+  ]) {
+    test(`screen-space diagonal picking follows the ${camera.type} view`, () => {
+      camera.position.set(5, 8, 10)
+      camera.lookAt(0, 0, 0)
+      camera.updateMatrixWorld(true)
+      const target = new Vector3(2, 0, 2)
+      const ndc = target.clone().project(camera)
+      const ray = new Raycaster()
+      ray.setFromCamera(new Vector2(ndc.x, ndc.y), camera)
+      const project = (point: RunPoint): [number, number] => {
+        const p = new Vector3(...point).project(camera)
+        return [(p.x + 1) * 400, (1 - p.y) * 300]
+      }
+      const result = projectRunToCameraDirection(
+        [0, 0, 0],
+        {
+          origin: ray.ray.origin.toArray(),
+          direction: ray.ray.direction.toArray(),
+        },
+        [1, 0, 0],
+        0.05,
+        0,
+        [
+          [1, 0, 0],
+          [0, 0, 1],
+          [Math.SQRT1_2, 0, Math.SQRT1_2],
+        ],
+        undefined,
+        {
+          project,
+          pointer: project(target.toArray()),
+          previous: [1, 0, 0],
+        },
+      )
+      expect(result?.direction).toEqual([Math.SQRT1_2, 0, Math.SQRT1_2])
+      expect(result?.point[0]).toBeCloseTo(2)
+      expect(result?.point[2]).toBeCloseTo(2)
+    })
+  }
+  test('releases an airborne direction guide when the cursor returns to a wall', () => {
+    const start: RunPoint = [0, 1, 1]
+    const ray: RunCursorRay = {
+      origin: [3, 3, 5],
+      direction: [-1, -1, -2],
+    }
+    const directions: RunPoint[] = [[1, 0, 0]]
+    expect(
+      projectRunToCameraDirection(start, ray, [1, 0, 0], 0.05, 0, directions)?.point[0],
+    ).toBeCloseTo(1)
+
+    for (const clearance of [0.0254, 0.1016]) {
+      const wall = createRunSurfaceFrame([0, 0, 2 + clearance], [0, 0, 1])
+      expect(
+        projectRunToCameraDirection(start, ray, [1, 0, 0], 0.05, 0, directions, wall),
+      ).toBeNull()
+    }
+  })
+
+  test('keeps direction guides that lie on the active wall face', () => {
+    const wall = createRunSurfaceFrame([0, 0, 1], [0, 0, 1])
+    const result = projectRunToCameraDirection(
+      [0, 1, 1],
+      { origin: [3, 3, 5], direction: [-1, -1, -2] },
+      [1, 0, 0],
+      0.05,
+      0,
+      [[1, 0, 0]],
+      wall,
+    )
+    expect(result?.point[0]).toBeCloseTo(1)
+    expect(result?.point[2]).toBe(1)
+  })
+
+  test('camera hover resolves downward without a ground-plane height', () => {
+    const projected = projectRunToCameraDirection(
+      [0, 5, 0],
+      { origin: [3, 2, 3], direction: [-Math.SQRT1_2, 0, -Math.SQRT1_2] },
+      [1, 0, 0],
+      0.05,
+      0,
+    )
+    expect(projected?.direction).toEqual([0, -1, 0])
+    expect(projected?.point[1]).toBeCloseTo(2)
+  })
+
+  test('projects the cursor onto the direction selected by an arrow handle', () => {
+    const point = projectRunToDirection([1, 2, 3], [4, 9, 1], [Math.SQRT1_2, 0, Math.SQRT1_2])
+
+    expect(point[1]).toBe(2)
+    expect(point[0] - 1).toBeCloseTo(point[2] - 3)
+    expect(point[0]).toBeGreaterThan(1)
+  })
+
+  test('snaps values only when the step is active', () => {
+    expect(snapRunValue(1.13, 0.25)).toBe(1.25)
+    expect(snapRunValue(1.13, 0)).toBe(1.13)
+  })
+
+  test('projects a cursor onto the nearest 45 degree ray', () => {
+    const point = projectRunToAngleLock([2, 3, 4], [4, 9, 5.8])
+
+    expect(point[1]).toBe(3)
+    expect(point[0] - 2).toBeCloseTo(point[2] - 4)
+  })
+
+  test('projects a connected continuation onto directions relative to its source run', () => {
+    const source = [Math.SQRT1_2, 0, Math.SQRT1_2] as const
+    const projected = projectRunToAngleLock([0, 0, 0], [1, 0, -2], source)
+
+    expect(projected[0]).toBeCloseTo(1.5)
+    expect(projected[1]).toBe(0)
+    expect(projected[2]).toBeCloseTo(-1.5)
+  })
+
+  test('selects a true vertical direction from the camera cursor ray', () => {
+    const projected = projectRunToCameraDirection(
+      [0, 0, 0],
+      {
+        origin: [3, 3, 3],
+        direction: [-Math.SQRT1_2, 0, -Math.SQRT1_2],
+      },
+      [1, 0, 0],
+      0.05,
+      0,
+    )
+
+    expect(projected?.direction[0]).toBeCloseTo(0)
+    expect(projected?.direction[1]).toBeCloseTo(1)
+    expect(projected?.direction[2]).toBeCloseTo(0)
+    expect(projected?.point[1]).toBeCloseTo(3)
+  })
+
+  test('selects a rising 45 degree direction in the source plane', () => {
+    const target = [Math.SQRT1_2 * 4, Math.SQRT1_2 * 4, 0] as const
+    const projected = projectRunToCameraDirection(
+      [0, 0, 0],
+      {
+        origin: [target[0] + 3, target[1], 3],
+        direction: [-Math.SQRT1_2, 0, -Math.SQRT1_2],
+      },
+      [1, 0, 0],
+      0.05,
+      0,
+    )
+
+    expect(projected?.direction[0]).toBeCloseTo(Math.SQRT1_2)
+    expect(projected?.direction[1]).toBeCloseTo(Math.SQRT1_2)
+    expect(projected?.direction[2]).toBeCloseTo(0)
+  })
+
+  test('steps from off-catalogue sizes using the nearest nominal size', () => {
+    const sizes = [2, 3, 4, 6]
+
+    expect(stepNominalRunSize(sizes, 3.2, 1)).toBe(4)
+    expect(stepNominalRunSize(sizes, 3.2, -1)).toBe(2)
+    expect(stepNominalRunSize(sizes, 6, 1)).toBe(6)
+  })
+
+  test('computes squared 3D distance for fitting degeneracy checks', () => {
+    expect(runDistanceSquared([1, 2, 3], [4, 6, 3])).toBe(25)
+  })
+
+  test('projects and snaps a run in a vertical wall plane', () => {
+    const wall = createRunSurfaceFrame([4, 2, 6], [0, 0, 1])
+
+    expect(projectRunPointToSurface([7, 3, 9], wall)).toEqual([7, 3, 6])
+    expect(snapRunPointToSurface([7.12, 2.88, 6], wall, 0.25)).toEqual([7, 3, 6])
+  })
+
+  test('keeps angle snapping inside the active surface plane', () => {
+    const wall = createRunSurfaceFrame([0, 1, 4], [0, 0, 1])
+    const point = projectRunToSurfaceAngleLock([0, 1, 4], [1.2, 2.1, 4], wall)
+
+    expect(point[2]).toBeCloseTo(4)
+    expect(point[1] - 1).toBeCloseTo(point[0])
+  })
+
+  test('keeps a run on a rotated wall plane', () => {
+    const diagonalWall = createRunSurfaceFrame([2, 1, 2], [Math.SQRT1_2, 0, Math.SQRT1_2])
+    const projected = projectRunPointToSurface([4, 3, 0], diagonalWall)
+
+    expect(projected[0] + projected[2]).toBeCloseTo(4)
+    expect(projected[1]).toBeCloseTo(3)
+  })
+})