@pascal-app/editor 1.0.4 → 1.0.5

package/src/components/tools/distribution/draw-alignment.ts

@@ -0,0 +1,35 @@
+'use client'
+
+import { alignFloorplanDraftPoint, useAlignmentGuides } from '@pascal-app/editor'
+
+type Vec3 = [number, number, number]
+
+/**
+ * Layer Figma-style alignment guides onto a draw-tool cursor point so HVAC /
+ * DWV runs and equipment line up with each other (and every other node) while
+ * being drawn — the same feedback walls get.
+ *
+ * Treats the point as a single corner anchor, gathers candidates from the live
+ * scene (every kind contributes via `nodeAlignmentAnchors`), publishes the
+ * guides to `useAlignmentGuides` (rendered in BOTH the 2D floor plan and the
+ * 3D view), and returns the point with the snap applied. Y is preserved — only
+ * XZ is aligned.
+ *
+ * - `applySnap: false` publishes the guide passively without pulling the point
+ *   off a constrained ray (e.g. an angle-locked run continuation).
+ * - `bypass: true` clears guides and returns the point untouched (Alt, or when
+ *   a stronger port / run-body snap already won).
+ */
+export function alignDrawPoint(point: Vec3, opts: { applySnap: boolean; bypass?: boolean }): Vec3 {
+  if (opts.bypass) {
+    useAlignmentGuides.getState().clear()
+    return point
+  }
+  const [x, z] = alignFloorplanDraftPoint([point[0], point[2]], { applySnap: opts.applySnap })
+  return [x, point[1], z]
+}
+
+/** Drop any alignment guides this tool published (cancel / commit / unmount). */
+export function clearDrawAlignment(): void {
+  useAlignmentGuides.getState().clear()
+}

package/src/components/tools/distribution/ports.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test'
+import type { RunSurfaceTarget } from './distribution-run-contract'
+import { findNearestPort3D, findNearestPortXZ, type ScenePort } from './ports'
+
+const ports: ScenePort[] = [
+  {
+    nodeId: 'duct-segment_a',
+    id: 'floor',
+    position: [0, 0, 0],
+    diameter: 0.1,
+    direction: [1, 0, 0],
+  },
+  {
+    nodeId: 'duct-segment_b',
+    id: 'wall',
+    position: [0.4, 2, 0],
+    diameter: 0.1,
+    direction: [1, 0, 0],
+  },
+]
+
+describe('distribution port distance metrics', () => {
+  test('wall drafting uses true 3D distance', () => {
+    expect(findNearestPort3D([0.4, 1.8, 0], ports, 0.5)?.id).toBe('wall')
+    expect(findNearestPort3D([0, 1.8, 0], ports, 0.1)).toBeNull()
+  })
+
+  test('floor drafting retains the legacy XZ metric', () => {
+    expect(findNearestPortXZ([0, 1.8, 0], ports, 0.1)?.id).toBe('floor')
+  })
+
+  test('wall drafting rejects a nearby port on the wrong plane', () => {
+    const wall: RunSurfaceTarget = {
+      kind: 'wall',
+      levelId: 'level_1',
+      hostId: 'wall_1',
+      side: 'front',
+      frame: {
+        origin: [0, 0, 0],
+        normal: [0, 0, 1],
+        tangent: [1, 0, 0],
+        bitangent: [0, 1, 0],
+      },
+      bounds: { minU: 0, maxU: 10, minV: 0, maxV: 3 },
+    }
+    const offPlane: ScenePort = {
+      nodeId: 'duct-segment_c',
+      id: 'off-plane',
+      position: [0, 1.8, 0.25],
+      diameter: 0.1,
+      direction: [1, 0, 0],
+    }
+    expect(findNearestPort3D([0, 1.8, 0], [offPlane], 0.1, wall)).toBeNull()
+    expect(findNearestPort3D([0.4, 2, 0], ports, 0.1, wall)?.id).toBe('wall')
+  })
+})

package/src/components/tools/distribution/ports.ts

@@ -0,0 +1,378 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  findLevelAncestorId,
+  type NodePort,
+  nodeRegistry,
+  useScene,
+} from '@pascal-app/core'
+import type { RunSurfaceTarget } from './distribution-run-contract'
+
+/** A port plus the scene node that owns it. */
+export type ScenePort = NodePort & { nodeId: AnyNodeId }
+
+/**
+ * Filter narrowing which ports a tool will snap to.
+ *   - `excludeNodeId` skips the node currently being drawn/placed so a
+ *     tool doesn't snap to its own preview.
+ *   - `systems` keeps only ports on the listed distribution loops — duct
+ *     tools pass the air loops so they ignore refrigerant service ports;
+ *     the lineset tool passes `'refrigerant'` so it ignores duct collars.
+ *     A port with no `system` matches any filter.
+ */
+export type PortFilter = {
+  levelId?: AnyNodeId
+  excludeNodeId?: AnyNodeId
+  systems?: readonly string[]
+}
+
+/**
+ * Gather every typed port in the scene by asking each node's registered
+ * `def.ports`. Positions are level-local meters (the kind applies its own
+ * transform inside `def.ports`).
+ */
+export function collectScenePorts(
+  filter: PortFilter = {},
+  sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>,
+): ScenePort[] {
+  const { excludeNodeId, systems, levelId } = filter
+  const nodes = sceneNodes ?? useScene.getState().nodes
+  const result: ScenePort[] = []
+  for (const node of Object.values(nodes)) {
+    if (
+      !node ||
+      node.visible === false ||
+      node.id === excludeNodeId ||
+      (levelId && findLevelAncestorId(node.id, nodes) !== levelId)
+    )
+      continue
+    const ports = nodeRegistry.get(node.type)?.ports?.(node)
+    if (!ports) continue
+    for (const port of ports) {
+      if (systems && port.system !== undefined && !systems.includes(port.system)) continue
+      result.push({ ...port, nodeId: node.id })
+    }
+  }
+  return result
+}
+
+/**
+ * Nearest port within `radius` of `point` on the XZ plane. Y is ignored —
+ * grid events ride the floor plane while ports usually hang at duct
+ * height, so a vertical-distance check would make elevated ports
+ * unreachable. The snap adopts the port's full 3D position.
+ */
+export function findNearestPortXZ(
+  point: readonly [number, number, number],
+  ports: ScenePort[],
+  radius: number,
+): ScenePort | null {
+  let best: ScenePort | null = null
+  let bestDistSq = radius * radius
+  for (const port of ports) {
+    const dx = port.position[0] - point[0]
+    const dz = port.position[2] - point[2]
+    const distSq = dx * dx + dz * dz
+    if (distSq <= bestDistSq) {
+      bestDistSq = distSq
+      best = port
+    }
+  }
+  return best
+}
+
+/** Nearest port using true 3D distance. Use this while drafting on a wall. */
+export function findNearestPort3D(
+  point: readonly [number, number, number],
+  ports: ScenePort[],
+  radius: number,
+  surface?: RunSurfaceTarget | null,
+): ScenePort | null {
+  let best: ScenePort | null = null
+  let bestDistSq = radius * radius
+  for (const port of ports) {
+    if (surface?.kind === 'wall') {
+      const planeDistance =
+        (port.position[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+        (port.position[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+        (port.position[2] - surface.frame.origin[2]) * surface.frame.normal[2]
+      if (Math.abs(planeDistance) > radius) continue
+    }
+    const dx = port.position[0] - point[0]
+    const dy = port.position[1] - point[1]
+    const dz = port.position[2] - point[2]
+    const distSq = dx * dx + dy * dy + dz * dz
+    if (distSq <= bestDistSq) {
+      bestDistSq = distSq
+      best = port
+    }
+  }
+  return best
+}
+
+// ─── Run-body hits ───────────────────────────────────────────────────
+
+/** Closest-point hit on a run's centerline (not its end ports). */
+export type RunBodyHit = {
+  nodeId: AnyNodeId
+  /** Polyline segment hit — between `path[segmentIndex]` and `path[segmentIndex + 1]`. */
+  segmentIndex: number
+  /** Closest point on the centerline, level-local meters (Y interpolated). */
+  point: [number, number, number]
+}
+
+/**
+ * Nearest point on any run CENTERLINE of the given kinds within `radius` of `point`
+ * on the XZ plane — how a branch taps the side of a trunk. Same XZ-only
+ * distance convention as `findNearestPortXZ` (grid events ride the floor,
+ * runs hang above it); the hit adopts the centerline's full 3D
+ * position. Vertical risers project to a point in XZ and are skipped —
+ * tapping those isn't meaningful.
+ */
+export function findNearestRunBodyXZ(
+  point: readonly [number, number, number],
+  radius: number,
+  filter: { excludeNodeId?: AnyNodeId; kinds: readonly string[]; levelId?: AnyNodeId },
+  sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>,
+): RunBodyHit | null {
+  const { kinds } = filter
+  const nodes = sceneNodes ?? useScene.getState().nodes
+  let best: RunBodyHit | null = null
+  let bestDistSq = radius * radius
+  for (const node of Object.values(nodes)) {
+    if (!node || !kinds.includes(node.type) || node.id === filter.excludeNodeId) continue
+    if (filter.levelId && findLevelAncestorId(node.id, nodes) !== filter.levelId) continue
+    const path = (node as { path?: Array<readonly [number, number, number]> }).path
+    if (!path) continue
+    for (let i = 0; i < path.length - 1; i++) {
+      const a = path[i]!
+      const b = path[i + 1]!
+      const abx = b[0] - a[0]
+      const abz = b[2] - a[2]
+      const lenSq = abx * abx + abz * abz
+      if (lenSq < 1e-8) continue // vertical riser — no XZ extent
+      const t = Math.min(
+        1,
+        Math.max(0, ((point[0] - a[0]) * abx + (point[2] - a[2]) * abz) / lenSq),
+      )
+      const cx = a[0] + abx * t
+      const cz = a[2] + abz * t
+      const dx = point[0] - cx
+      const dz = point[2] - cz
+      const distSq = dx * dx + dz * dz
+      if (distSq <= bestDistSq) {
+        bestDistSq = distSq
+        best = {
+          nodeId: node.id,
+          segmentIndex: i,
+          point: [cx, a[1] + (b[1] - a[1]) * t, cz],
+        }
+      }
+    }
+  }
+  return best
+}
+
+/** Nearest run centerline point using true 3D distance, including risers. */
+export function findNearestRunBody3D(
+  point: readonly [number, number, number],
+  radius: number,
+  filter: { excludeNodeId?: AnyNodeId; kinds: readonly string[]; levelId?: AnyNodeId },
+  surface?: RunSurfaceTarget | null,
+  sceneNodes?: Readonly<Record<AnyNodeId, AnyNode>>,
+): RunBodyHit | null {
+  const { kinds } = filter
+  const nodes = sceneNodes ?? useScene.getState().nodes
+  let best: RunBodyHit | null = null
+  let bestDistSq = radius * radius
+  for (const node of Object.values(nodes)) {
+    if (!node || !kinds.includes(node.type) || node.id === filter.excludeNodeId) continue
+    if (filter.levelId && findLevelAncestorId(node.id, nodes) !== filter.levelId) continue
+    if (node.visible === false) continue
+    const path = (node as { path?: Array<readonly [number, number, number]> }).path
+    if (!path) continue
+    for (let i = 0; i < path.length - 1; i++) {
+      const a = path[i]!
+      const b = path[i + 1]!
+      if (surface?.kind === 'wall') {
+        const aPlane =
+          (a[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+          (a[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+          (a[2] - surface.frame.origin[2]) * surface.frame.normal[2]
+        const bPlane =
+          (b[0] - surface.frame.origin[0]) * surface.frame.normal[0] +
+          (b[1] - surface.frame.origin[1]) * surface.frame.normal[1] +
+          (b[2] - surface.frame.origin[2]) * surface.frame.normal[2]
+        if (Math.abs(aPlane) > radius && Math.abs(bPlane) > radius) continue
+      }
+      const abx = b[0] - a[0]
+      const aby = b[1] - a[1]
+      const abz = b[2] - a[2]
+      const lenSq = abx * abx + aby * aby + abz * abz
+      if (lenSq < 1e-8) continue
+      const t = Math.min(
+        1,
+        Math.max(
+          0,
+          ((point[0] - a[0]) * abx + (point[1] - a[1]) * aby + (point[2] - a[2]) * abz) / lenSq,
+        ),
+      )
+      const hit: [number, number, number] = [a[0] + abx * t, a[1] + aby * t, a[2] + abz * t]
+      const dx = point[0] - hit[0]
+      const dy = point[1] - hit[1]
+      const dz = point[2] - hit[2]
+      const distSq = dx * dx + dy * dy + dz * dz
+      if (distSq <= bestDistSq) {
+        bestDistSq = distSq
+        best = { nodeId: node.id, segmentIndex: i, point: hit }
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * Where a drawn segment `start`→`end` crosses straight THROUGH an
+ * existing run's centerline in XZ — the four-way (cross) case, as
+ * opposed to ending ON a run (the tee case). The crossing must be
+ * INTERIOR to both: strictly between the drawn segment's ends (so the
+ * run truly passes through, not just touches at a tip — those are tee
+ * taps) and strictly inside the hit trunk segment, clear of its joints
+ * by `endMargin` meters so the run legs have room. The hit's `point`
+ * adopts the trunk centerline's interpolated 3D position (the drawn run
+ * snaps onto the trunk's height). Returns the nearest such crossing, or
+ * null. Vertical risers (no XZ extent) are skipped, same as the body
+ * query.
+ */
+export function findRunBodyCrossingXZ(
+  start: readonly [number, number, number],
+  end: readonly [number, number, number],
+  endMargin: number,
+  filter: { excludeNodeId?: AnyNodeId; kinds: readonly string[] },
+): RunBodyHit | null {
+  const { kinds } = filter
+  const { nodes } = useScene.getState()
+  const dx = end[0] - start[0]
+  const dz = end[2] - start[2]
+  const drawnLenSq = dx * dx + dz * dz
+  if (drawnLenSq < 1e-8) return null
+  const drawnLen = Math.sqrt(drawnLenSq)
+  // Interior margins as a fraction of each segment's length.
+  const drawnPad = Math.min(0.45, endMargin / drawnLen)
+  let best: RunBodyHit | null = null
+  let bestScore = Number.POSITIVE_INFINITY
+  for (const node of Object.values(nodes)) {
+    if (!node || !kinds.includes(node.type) || node.id === filter.excludeNodeId) continue
+    const path = (node as { path?: Array<readonly [number, number, number]> }).path
+    if (!path) continue
+    for (let i = 0; i < path.length - 1; i++) {
+      const a = path[i]!
+      const b = path[i + 1]!
+      const ex = b[0] - a[0]
+      const ez = b[2] - a[2]
+      const runLenSq = ex * ex + ez * ez
+      if (runLenSq < 1e-8) continue // vertical riser — no XZ extent
+      // Solve start + s·d = a + t·e in XZ. denom is the 2D cross of the
+      // two directions; ~0 means parallel (no single crossing).
+      const denom = dx * ez - dz * ex
+      if (Math.abs(denom) < 1e-9) continue
+      const wx = a[0] - start[0]
+      const wz = a[2] - start[2]
+      const s = (wx * ez - wz * ex) / denom
+      const t = (wx * dz - wz * dx) / denom
+      const runLen = Math.sqrt(runLenSq)
+      const runPad = Math.min(0.45, endMargin / runLen)
+      // Strictly interior to both segments, clear of the trunk's joints.
+      if (s <= drawnPad || s >= 1 - drawnPad) continue
+      if (t <= runPad || t >= 1 - runPad) continue
+      // Prefer the crossing nearest the drawn start (first run hit).
+      if (s < bestScore) {
+        bestScore = s
+        best = {
+          nodeId: node.id,
+          segmentIndex: i,
+          point: [a[0] + ex * t, a[1] + (b[1] - a[1]) * t, a[2] + ez * t],
+        }
+      }
+    }
+  }
+  return best
+}
+
+/** Surface-local crossing for wall drafting. Intersects projected U/V lines
+ * and ignores runs that are not coplanar with the selected wall. */
+export function findRunBodyCrossingSurface(
+  start: readonly [number, number, number],
+  end: readonly [number, number, number],
+  endMargin: number,
+  surface: RunSurfaceTarget,
+  filter: { excludeNodeId?: AnyNodeId; kinds: readonly string[] },
+): RunBodyHit | null {
+  const project = (p: readonly [number, number, number]): [number, number, number] => {
+    const d: [number, number, number] = [
+      p[0] - surface.frame.origin[0],
+      p[1] - surface.frame.origin[1],
+      p[2] - surface.frame.origin[2],
+    ]
+    return [
+      d[0] * surface.frame.tangent[0] +
+        d[1] * surface.frame.tangent[1] +
+        d[2] * surface.frame.tangent[2],
+      d[0] * surface.frame.bitangent[0] +
+        d[1] * surface.frame.bitangent[1] +
+        d[2] * surface.frame.bitangent[2],
+      d[0] * surface.frame.normal[0] +
+        d[1] * surface.frame.normal[1] +
+        d[2] * surface.frame.normal[2],
+    ]
+  }
+  const s0 = project(start),
+    s1 = project(end)
+  const dx = s1[0] - s0[0],
+    dy = s1[1] - s0[1]
+  const drawnLen = Math.hypot(dx, dy)
+  if (drawnLen < 1e-8) return null
+  const drawnPad = Math.min(0.45, endMargin / drawnLen)
+  const { kinds } = filter
+  const { nodes } = useScene.getState()
+  let best: RunBodyHit | null = null
+  let bestScore = Number.POSITIVE_INFINITY
+  for (const node of Object.values(nodes)) {
+    if (
+      !node ||
+      node.visible === false ||
+      node.parentId !== surface.levelId ||
+      !kinds.includes(node.type) ||
+      node.id === filter.excludeNodeId
+    )
+      continue
+    const path = (node as { path?: Array<readonly [number, number, number]> }).path
+    if (!path) continue
+    for (let i = 0; i < path.length - 1; i++) {
+      const a = path[i]!,
+        b = path[i + 1]!,
+        pa = project(a),
+        pb = project(b)
+      const ex = pb[0] - pa[0],
+        ey = pb[1] - pa[1],
+        runLen = Math.hypot(ex, ey)
+      const denom = dx * ey - dy * ex
+      if (runLen < 1e-8 || Math.abs(denom) < 1e-9) continue
+      const wx = pa[0] - s0[0],
+        wy = pa[1] - s0[1]
+      const s = (wx * ey - wy * ex) / denom,
+        t = (wx * dy - wy * dx) / denom
+      if (Math.abs(pa[2] + t * (pb[2] - pa[2]) - (s0[2] + s * (s1[2] - s0[2]))) > 0.01) continue
+      const runPad = Math.min(0.45, endMargin / runLen)
+      if (s <= drawnPad || s >= 1 - drawnPad || t <= runPad || t >= 1 - runPad || s >= bestScore)
+        continue
+      bestScore = s
+      best = {
+        nodeId: node.id,
+        segmentIndex: i,
+        point: [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t],
+      }
+    }
+  }
+  return best
+}

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

@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test'
+import type { AnyNodeId } from '@pascal-app/core'
+import {
+  createRunSurfaceFrame,
+  isSameRunWallSurface,
+  shouldLockRunWallSurface,
+} from './distribution-run-tool'
+import { intersectRunPlane, resolveRunCursorPlane } from './run-cursor'
+
+describe('surface-first run cursor', () => {
+  test('matches only the wall host and face that started the draft', () => {
+    const target = {
+      kind: 'wall' as const,
+      levelId: 'level-1' as AnyNodeId,
+      hostId: 'wall-1' as AnyNodeId,
+      side: 'front' as const,
+      frame: createRunSurfaceFrame([0, 0, 0], [0, 0, 1]),
+      bounds: { minU: -1, maxU: 1, minV: -1, maxV: 1 },
+    }
+
+    expect(
+      isSameRunWallSurface(target, {
+        kind: 'wall',
+        hostId: target.hostId,
+        face: 'side',
+        side: 'front',
+      }),
+    ).toBe(true)
+    expect(
+      isSameRunWallSurface(target, {
+        kind: 'wall',
+        hostId: target.hostId,
+        face: 'side',
+        side: 'back',
+      }),
+    ).toBe(false)
+    expect(
+      isSameRunWallSurface(target, {
+        kind: 'wall',
+        hostId: 'wall-2',
+        face: 'side',
+        side: 'front',
+      }),
+    ).toBe(false)
+  })
+
+  test('locks a wall only when the start is not snapped to a body or port', () => {
+    const target = {
+      kind: 'wall' as const,
+      levelId: 'level-1' as AnyNodeId,
+      hostId: 'wall-1' as AnyNodeId,
+      side: 'front' as const,
+      frame: createRunSurfaceFrame([0, 0, 0], [0, 0, 1]),
+      bounds: { minU: 0, maxU: 1, minV: 0, maxV: 1 },
+    }
+
+    expect(shouldLockRunWallSurface(target, { port: null, body: null })).toBe(true)
+    expect(shouldLockRunWallSurface(target, { port: {} as never, body: null })).toBe(false)
+    expect(shouldLockRunWallSurface(target, { port: null, body: {} as never })).toBe(false)
+  })
+
+  test('reacquires either ceiling face from free space with duct or pipe clearance', () => {
+    for (const side of [-1, 1]) {
+      for (const clearance of [0.0254, 0.1016]) {
+        const result = resolveRunCursorPlane({
+          hit: {
+            point: [2, 3, 4],
+            frame: createRunSurfaceFrame([0, 3, 0], [0, side, 0]),
+          },
+          working: createRunSurfaceFrame([0, 1, 0]),
+          fallback: [2, 1, 4],
+          clearance,
+        })
+        expect(result.point[1]).toBeCloseTo(3 + side * clearance)
+        expect(result.frame.origin[1]).toBeCloseTo(result.point[1])
+        expect(result.frame.normal).toEqual([0, side, 0])
+      }
+    }
+  })
+
+  test('wall hit wins over a ground fallback and applies clearance once', () => {
+    const frame = createRunSurfaceFrame([0, 0, 2], [0, 0, 1])
+    const result = resolveRunCursorPlane({
+      hit: { point: [1, 1.5, 2], frame },
+      working: null,
+      fallback: [9, 0, 9],
+      clearance: 0.0508,
+    })
+    expect(result.point).toEqual([1, 1.5, 2.0508])
+  })
+  test('empty space continues on the wall plane along the actual mouse ray', () => {
+    const frame = createRunSurfaceFrame([0, 0, 2], [0, 0, 1])
+    const result = resolveRunCursorPlane({
+      hit: null,
+      working: frame,
+      ray: { origin: [0, 4, 6], direction: [1, -0.5, -1] },
+      fallback: [0, 0, 0],
+      clearance: 0.1,
+    })
+    expect(result.point).toEqual([4, 2, 2])
+  })
+  test('ceiling target replaces wall plane and offsets downward', () => {
+    const result = resolveRunCursorPlane({
+      hit: { point: [2, 3, 4], frame: createRunSurfaceFrame([0, 3, 0], [0, -1, 0]) },
+      working: createRunSurfaceFrame([0, 0, 4], [0, 0, 1]),
+      fallback: [0, 0, 0],
+      clearance: 0.1,
+    })
+    expect(result.point).toEqual([2, 2.9, 4])
+  })
+  test('parallel and behind-camera intersections preserve the last point', () => {
+    const working = createRunSurfaceFrame([0, 0, 2], [0, 0, 1])
+    expect(intersectRunPlane({ origin: [0, 0, 0], direction: [0, 0, -1] }, working)).toBeNull()
+    expect(
+      resolveRunCursorPlane({
+        hit: null,
+        working,
+        ray: { origin: [0, 0, 0], direction: [1, 0, 0] },
+        fallback: [1, 2, 2],
+        clearance: 0,
+      }).point,
+    ).toEqual([1, 2, 2])
+  })
+  test('floor and sloped planes use their own normal for clearance', () => {
+    const frame = createRunSurfaceFrame([0, 2, 0], [0, Math.SQRT1_2, Math.SQRT1_2])
+    const result = resolveRunCursorPlane({
+      hit: { point: [0, 2, 0], frame },
+      working: null,
+      fallback: [0, 0, 0],
+      clearance: 0.1,
+    })
+    expect(result.point[1]).toBeCloseTo(2 + Math.SQRT1_2 * 0.1)
+    expect(result.point[2]).toBeCloseTo(Math.SQRT1_2 * 0.1)
+  })
+})

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

@@ -0,0 +1,36 @@
+import type { RunPoint, RunSurfaceFrame } from './distribution-run-contract'
+
+export function intersectRunPlane(
+  ray: { origin: RunPoint; direction: RunPoint },
+  frame: RunSurfaceFrame,
+): RunPoint | null {
+  const denominator = ray.direction.reduce((sum, value, i) => sum + value * frame.normal[i]!, 0)
+  if (Math.abs(denominator) < 1e-5) return null
+  const distance =
+    frame.origin.reduce((sum, value, i) => sum + (value - ray.origin[i]!) * frame.normal[i]!, 0) /
+    denominator
+  if (distance < 0 || !Number.isFinite(distance)) return null
+  return ray.origin.map((value, i) => value + distance * ray.direction[i]!) as RunPoint
+}
+
+export function resolveRunCursorPlane({
+  hit,
+  working,
+  ray,
+  fallback,
+  clearance,
+}: {
+  hit: { point: RunPoint; frame: RunSurfaceFrame } | null
+  working: RunSurfaceFrame | null
+  ray?: { origin: RunPoint; direction: RunPoint }
+  fallback: RunPoint
+  clearance: number
+}): { point: RunPoint; frame: RunSurfaceFrame } {
+  if (hit) {
+    const offset = (point: RunPoint): RunPoint =>
+      point.map((value, i) => value + hit.frame.normal[i]! * clearance) as RunPoint
+    return { point: offset(hit.point), frame: { ...hit.frame, origin: offset(hit.frame.origin) } }
+  }
+  if (!working) throw new Error('A cursor requires a surface or a working plane')
+  return { point: ray ? (intersectRunPlane(ray, working) ?? fallback) : fallback, frame: working }
+}