@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/floorplan/site-plan/geometry.ts

@@ -0,0 +1,557 @@
+import { arcRuns, insetPolygon, type KeepOut, sightTriangle, streetCorners } from '@pascal-app/core'
+/**
+ * Site-plan geometry — pure functions, no store, no React.
+ *
+ * All coordinates are SITE metres: origin = the geocoded point, x → east,
+ * y → south (the plan frame the site polygon is stored in). Consumers
+ * (2D editor, sheets) turn these into SVG through the existing renderer.
+ */
+
+export type Pt = readonly [number, number]
+
+export interface Bounds {
+  minX: number
+  minY: number
+  maxX: number
+  maxY: number
+}
+
+/** Yard sides in the order the site-plan dimensions are cast. */
+export type YardSide = 'north' | 'south' | 'east' | 'west'
+
+export interface SetbackInputs {
+  front: number
+  side: number
+  rear: number
+  left?: number
+  right?: number
+  /** A corner lot's second street side; absent = the front setback. */
+  streetSide?: number
+}
+
+/** Per-edge classification of a lot polygon relative to its front edge. */
+export type EdgeRole = 'front' | 'rear' | 'left' | 'right' | 'street' | 'street'
+
+const EPS = 1e-9
+
+export function polygonBounds(points: readonly Pt[]): Bounds {
+  let minX = Number.POSITIVE_INFINITY
+  let minY = Number.POSITIVE_INFINITY
+  let maxX = Number.NEGATIVE_INFINITY
+  let maxY = Number.NEGATIVE_INFINITY
+  for (const [x, y] of points) {
+    if (x < minX) minX = x
+    if (x > maxX) maxX = x
+    if (y < minY) minY = y
+    if (y > maxY) maxY = y
+  }
+  if (!Number.isFinite(minX)) return { minX: 0, minY: 0, maxX: 0, maxY: 0 }
+  return { minX, minY, maxX, maxY }
+}
+
+export function polygonArea(points: readonly Pt[]): number {
+  let a = 0
+  for (let i = 0, n = points.length; i < n; i++) {
+    const p = points[i] as Pt
+    const q = points[(i + 1) % n] as Pt
+    a += p[0] * q[1] - q[0] * p[1]
+  }
+  return Math.abs(a / 2)
+}
+
+export function polygonCentroid(points: readonly Pt[]): Pt {
+  let cx = 0
+  let cy = 0
+  let a = 0
+  for (let i = 0, n = points.length; i < n; i++) {
+    const p = points[i] as Pt
+    const q = points[(i + 1) % n] as Pt
+    const cross = p[0] * q[1] - q[0] * p[1]
+    a += cross
+    cx += (p[0] + q[0]) * cross
+    cy += (p[1] + q[1]) * cross
+  }
+  if (Math.abs(a) < EPS) {
+    // Degenerate ring — fall back to the vertex average.
+    const n = Math.max(1, points.length)
+    let sx = 0
+    let sy = 0
+    for (const [x, y] of points) {
+      sx += x
+      sy += y
+    }
+    return [sx / n, sy / n]
+  }
+  a /= 2
+  return [cx / (6 * a), cy / (6 * a)]
+}
+
+/** True when the ring is wound counter-clockwise in a y-down (south-positive) frame. */
+export function isCounterClockwise(points: readonly Pt[]): boolean {
+  let a = 0
+  for (let i = 0, n = points.length; i < n; i++) {
+    const p = points[i] as Pt
+    const q = points[(i + 1) % n] as Pt
+    a += p[0] * q[1] - q[0] * p[1]
+  }
+  return a > 0
+}
+
+/**
+ * Unit normal of edge `i` pointing OUT of the polygon, winding-agnostic.
+ */
+export function outwardNormal(points: readonly Pt[], i: number): Pt {
+  const n = points.length
+  const p = points[i % n] as Pt
+  const q = points[(i + 1) % n] as Pt
+  const dx = q[0] - p[0]
+  const dy = q[1] - p[1]
+  const len = Math.hypot(dx, dy) || 1
+  // Left normal of the edge direction. For a CCW ring (positive shoelace in
+  // this frame) the left normal points inward, so flip.
+  const sign = isCounterClockwise(points) ? -1 : 1
+  return [(sign * -dy) / len, (sign * dx) / len]
+}
+
+/**
+ * Compass heading of edge `i`'s outward normal, in DEGREES clockwise from
+ * north, where `northRotation` (radians, clockwise) is true north's offset
+ * from plan up (−y). This is the direction the edge faces.
+ */
+export function edgeHeadingDeg(points: readonly Pt[], i: number, northRotation = 0): number {
+  const [nx, ny] = outwardNormal(points, i)
+  // Plan up (−y) is 0°, +x (east) is 90°.
+  const raw = Math.atan2(nx, -ny) - northRotation
+  const deg = (raw * 180) / Math.PI
+  return ((deg % 360) + 360) % 360
+}
+
+const COMPASS = [
+  'N',
+  'NNE',
+  'NE',
+  'ENE',
+  'E',
+  'ESE',
+  'SE',
+  'SSE',
+  'S',
+  'SSW',
+  'SW',
+  'WSW',
+  'W',
+  'WNW',
+  'NW',
+  'NNW',
+]
+
+export function compassLabel(headingDeg: number): string {
+  const idx = Math.round((((headingDeg % 360) + 360) % 360) / 22.5) % 16
+  return COMPASS[idx] as string
+}
+
+/** Length of edge `i`, metres. */
+export function edgeLength(points: readonly Pt[], i: number): number {
+  const n = points.length
+  const p = points[i % n] as Pt
+  const q = points[(i + 1) % n] as Pt
+  return Math.hypot(q[0] - p[0], q[1] - p[1])
+}
+
+/**
+ * Fallback front edge: the edge whose outward normal points closest to true
+ * north. Ties break toward the longer edge — the street frontage of a typical
+ * lot is one of its long sides.
+ */
+export function mostNorthFacingEdge(points: readonly Pt[], northRotation = 0): number {
+  let best = 0
+  let bestScore = Number.POSITIVE_INFINITY
+  for (let i = 0; i < points.length; i++) {
+    const heading = edgeHeadingDeg(points, i, northRotation)
+    const off = Math.min(heading, 360 - heading)
+    // Sub-degree ties resolve on length so a chamfer corner never wins.
+    const score = off - Math.min(0.5, edgeLength(points, i) / 1000)
+    if (score < bestScore) {
+      bestScore = score
+      best = i
+    }
+  }
+  return best
+}
+
+/** `frontEdge` if it indexes a real edge, else the most north-facing edge. */
+export function resolveFrontEdge(
+  points: readonly Pt[],
+  frontEdge: number | undefined,
+  northRotation = 0,
+): number {
+  if (
+    typeof frontEdge === 'number' &&
+    Number.isInteger(frontEdge) &&
+    frontEdge >= 0 &&
+    frontEdge < points.length
+  ) {
+    return frontEdge
+  }
+  return mostNorthFacingEdge(points, northRotation)
+}
+
+/**
+ * Classify every edge as front / rear / left / right.
+ *
+ * - front = `frontIndex`.
+ * - rear  = the edge whose outward normal is most anti-parallel to the front's.
+ * - the rest are sides. LEFT / RIGHT are defined along the FRONT EDGE
+ *   DIRECTION (`points[front] → points[front + 1]`): an edge whose midpoint
+ *   projects behind the front-edge midpoint on that axis is `left`, ahead of
+ *   it is `right`. Deterministic and independent of winding.
+ */
+export function classifyEdges(
+  points: readonly Pt[],
+  frontIndex: number,
+  streetEdges: readonly number[] = [],
+): EdgeRole[] {
+  const n = points.length
+  const roles: EdgeRole[] = new Array(n).fill('left')
+  if (n === 0) return roles
+
+  const front = ((frontIndex % n) + n) % n
+  const fn = outwardNormal(points, front)
+  // a corner lot's other street edges (the parcel fabric's frontage) are
+  // 'street' — they take the street-side setback, never a side yard, and
+  // the rear is never one of them
+  const street = new Set(streetEdges.map((i) => ((i % n) + n) % n))
+  street.delete(front)
+
+  let rear = -1
+  let rearDot = Number.POSITIVE_INFINITY
+  for (let i = 0; i < n; i++) {
+    if (i === front || street.has(i)) continue
+    const ni = outwardNormal(points, i)
+    const dot = fn[0] * ni[0] + fn[1] * ni[1]
+    if (dot < rearDot) {
+      rearDot = dot
+      rear = i
+    }
+  }
+
+  const fp = points[front] as Pt
+  const fq = points[(front + 1) % n] as Pt
+  const dx = fq[0] - fp[0]
+  const dy = fq[1] - fp[1]
+  const len = Math.hypot(dx, dy) || 1
+  const ux = dx / len
+  const uy = dy / len
+  const fmx = (fp[0] + fq[0]) / 2
+  const fmy = (fp[1] + fq[1]) / 2
+
+  for (let i = 0; i < n; i++) {
+    if (i === front) {
+      roles[i] = 'front'
+      continue
+    }
+    if (street.has(i)) {
+      roles[i] = 'street'
+      continue
+    }
+    if (i === rear) {
+      roles[i] = 'rear'
+      continue
+    }
+    const p = points[i] as Pt
+    const q = points[(i + 1) % n] as Pt
+    const mx = (p[0] + q[0]) / 2 - fmx
+    const my = (p[1] + q[1]) / 2 - fmy
+    roles[i] = mx * ux + my * uy < 0 ? 'left' : 'right'
+  }
+  return roles
+}
+
+/** Required setback distance (metres) for each edge role. */
+export function setbackForRole(setbacks: SetbackInputs, role: EdgeRole): number {
+  switch (role) {
+    case 'front':
+      return setbacks.front
+    case 'street':
+      return setbacks.streetSide ?? setbacks.front
+    case 'rear':
+      return setbacks.rear
+    case 'left':
+      return setbacks.left ?? setbacks.side
+    case 'right':
+      return setbacks.right ?? setbacks.side
+  }
+}
+
+/**
+ * Buildable envelope — every lot edge pushed INWARD by its own setback, with
+ * the new vertices taken as the intersections of adjacent offset lines
+ * (variable-distance straight-skeleton-lite). Exact for convex lots; on a
+ * concave lot a reflex corner can self-intersect, in which case the caller
+ * still gets a ring but it is advisory, not a legal envelope.
+ *
+ * Adjacent offset lines that are parallel (a straight run split by a
+ * surplus vertex) have no intersection: the shared vertex is then simply
+ * pushed inward along the current edge's own offset, instead of the whole
+ * envelope being refused.
+ *
+ * Returns `[]` when the polygon has fewer than 3 points or when the result
+ * inverts (setbacks larger than the lot).
+ */
+export function setbackEnvelope(
+  points: readonly Pt[],
+  setbacks: SetbackInputs,
+  frontIndex: number,
+  options: { streetEdges?: readonly number[]; sightTriangleM?: number } = {},
+): Pt[] {
+  const n = points.length
+  if (n < 3) return []
+  const streetEdges = options.streetEdges ?? []
+  const roles = classifyEdges(points, frontIndex, streetEdges)
+  // A radius drawn as a run of short edges takes ONE role. A curb return
+  // is street frontage: a run carrying, or touching, a front / street edge
+  // is front / street all along (otherwise the last sliver of the return
+  // became a side yard, and the envelope jutted out toward the corner); a
+  // run carrying the rear is rear; else
+  // each sliver keeps its own side.
+  const runs = arcRuns(points)
+  const runRole = new Map<number, EdgeRole>()
+  const streetLike = (r: EdgeRole) => r === 'front' || r === 'street'
+  for (let i = 0; i < n; i++) {
+    const r = roles[i] as EdgeRole
+    const g = runs[i] as number
+    const have = runRole.get(g)
+    if (streetLike(r) || (r === 'rear' && !(have && streetLike(have)))) runRole.set(g, r)
+    else if (!have) runRole.set(g, r)
+  }
+  for (let i = 0; i < n; i++) {
+    const g = runs[i] as number
+    const have = runRole.get(g) as EdgeRole
+    if (streetLike(have)) continue
+    const before = roles[(i - 1 + n) % n] as EdgeRole
+    const after = roles[(i + 1) % n] as EdgeRole
+    const members = runs.filter((x) => x === g).length
+    if (members > 1) {
+      if (runs[(i - 1 + n) % n] !== g && streetLike(before)) runRole.set(g, before)
+      else if (runs[(i + 1) % n] !== g && streetLike(after)) runRole.set(g, after)
+    }
+  }
+  // One lot line drawn as two: the county fabric splits a frontage at a kink of
+  // a degree or two, and only one half may come back from the street lookup
+  // (or the north-facing fallback). The half left out took a side yard, and
+  // the front yard swung round their shared corner in a circle as deep as
+  // itself. An edge running on nearly straight from a front or street edge
+  // is that frontage too.
+  const roleOf = (i: number) =>
+    runRole.get(runs[(i + n) % n] as number) ?? (roles[(i + n) % n] as EdgeRole)
+  const direction = (i: number) => {
+    const p = points[(i + n) % n] as Pt
+    const q = points[(i + 1 + n) % n] as Pt
+    const l = Math.hypot(q[0] - p[0], q[1] - p[1]) || 1
+    return [(q[0] - p[0]) / l, (q[1] - p[1]) / l] as const
+  }
+  const straightOn = Math.cos((8 * Math.PI) / 180)
+  const continued = new Map<number, EdgeRole>()
+  for (let pass = 0; pass < n; pass++) {
+    let grew = false
+    for (let i = 0; i < n; i++) {
+      const own = continued.get(i) ?? roleOf(i)
+      if (streetLike(own)) continue
+      const d = direction(i)
+      for (const j of [i - 1, i + 1]) {
+        const k = (j + n) % n
+        const theirs = continued.get(k) ?? roleOf(k)
+        const e = direction(k)
+        if (streetLike(theirs) && d[0] * e[0] + d[1] * e[1] > straightOn) {
+          continued.set(i, theirs)
+          grew = true
+          break
+        }
+      }
+    }
+    if (!grew) break
+  }
+  const distances: number[] = []
+  for (let i = 0; i < n; i++) {
+    const role = continued.get(i) ?? runRole.get(runs[i] as number) ?? (roles[i] as EdgeRole)
+    const d = setbackForRole(
+      setbacks,
+      role === 'left' || role === 'right' ? (roles[i] as EdgeRole) : role,
+    )
+    if (!Number.isFinite(d) || d < 0) return []
+    distances.push(d)
+  }
+  // the corner sight triangles keep the envelope out of the clear-vision
+  // zone at each street intersection (the hypotenuse is a half-plane)
+  const keepOut: KeepOut[] = []
+  if (options.sightTriangleM && options.sightTriangleM > 0) {
+    for (const [a, b] of streetCorners(points, [frontIndex, ...streetEdges])) {
+      const tri = sightTriangle(points, a, b, options.sightTriangleM)
+      if (tri) keepOut.push({ a: tri.a, b: tri.b, inside: tri.corner })
+    }
+  }
+  // the true inward offset (core setback-envelope.ts): straight where the
+  // lot is straight, concentric round a radius, clipped where the offsets
+  // cross — the industry-standard setback for pie shapes, radius corners
+  // and odd lots
+  return insetPolygon(points, distances, { keepOut })
+}
+
+/**
+ * Distance from `origin` along unit direction `(dx, dy)` to the first crossing
+ * of the polygon boundary. `null` when the ray never hits (origin outside, or
+ * a degenerate ring).
+ */
+export function rayToPolygon(
+  points: readonly Pt[],
+  origin: Pt,
+  dx: number,
+  dy: number,
+): { distance: number; point: Pt } | null {
+  const n = points.length
+  let best: { distance: number; point: Pt } | null = null
+  for (let i = 0; i < n; i++) {
+    const p = points[i] as Pt
+    const q = points[(i + 1) % n] as Pt
+    const ex = q[0] - p[0]
+    const ey = q[1] - p[1]
+    const denom = dx * ey - dy * ex
+    if (Math.abs(denom) < 1e-12) continue
+    // origin + t*d = p + u*e
+    const t = ((p[0] - origin[0]) * ey - (p[1] - origin[1]) * ex) / denom
+    const u = ((p[0] - origin[0]) * dy - (p[1] - origin[1]) * dx) / denom
+    if (t <= 1e-9 || u < -1e-9 || u > 1 + 1e-9) continue
+    if (!best || t < best.distance) {
+      best = { distance: t, point: [origin[0] + dx * t, origin[1] + dy * t] }
+    }
+  }
+  return best
+}
+
+export interface YardDimension {
+  side: YardSide
+  /** Bounding-box edge midpoint the dimension starts at. */
+  from: Pt
+  /** Where the cast ray meets the lot line. */
+  to: Pt
+  /** Metres. */
+  distance: number
+}
+
+/**
+ * The four yard dimensions: from each footprint bbox edge midpoint, straight
+ * out to the lot line. Sides whose ray misses the lot line (footprint outside
+ * the lot) are omitted rather than faked.
+ */
+export function castYardDimensions(lot: readonly Pt[], footprint: Bounds): YardDimension[] {
+  if (lot.length < 3) return []
+  const midX = (footprint.minX + footprint.maxX) / 2
+  const midY = (footprint.minY + footprint.maxY) / 2
+  const casts: { side: YardSide; from: Pt; dx: number; dy: number }[] = [
+    { side: 'north', from: [midX, footprint.minY], dx: 0, dy: -1 },
+    { side: 'south', from: [midX, footprint.maxY], dx: 0, dy: 1 },
+    { side: 'west', from: [footprint.minX, midY], dx: -1, dy: 0 },
+    { side: 'east', from: [footprint.maxX, midY], dx: 1, dy: 0 },
+  ]
+  const out: YardDimension[] = []
+  for (const c of casts) {
+    const hit = rayToPolygon(lot, c.from, c.dx, c.dy)
+    if (!hit) continue
+    out.push({ side: c.side, from: c.from, to: hit.point, distance: hit.distance })
+  }
+  return out
+}
+
+/**
+ * Yard dimensions for a building TURNED on its lot. The footprint's bounds
+ * are taken in the building's own frame (`yaw`, the building node's Y
+ * rotation), and the four edge midpoints cast square to the house's faces
+ * out to the lot line — the yards a plan checker measures. With `yaw` 0 this
+ * is the axis-aligned cast above; with a house square to a diagonal lot the
+ * axis-aligned bbox sticks out past the real corners and reads a front yard
+ * inches short of the setback it actually meets (Land Park, 2026-09-06).
+ * `side` is the compass direction nearest the cast, so labels keep reading
+ * N / S / E / W.
+ */
+export function castYardDimensionsOriented(
+  lot: readonly Pt[],
+  footprintLoops: readonly (readonly Pt[])[],
+  yaw: number,
+): YardDimension[] {
+  if (lot.length < 3) return []
+  const c = Math.cos(yaw)
+  const s = Math.sin(yaw)
+  // world = (c·lx + s·lz, −s·lx + c·lz)  ⇒  local = (c·wx − s·wz, s·wx + c·wz)
+  const toLocal = (p: Pt): Pt => [c * p[0] - s * p[1], s * p[0] + c * p[1]]
+  const toWorld = (p: Pt): Pt => [c * p[0] + s * p[1], -s * p[0] + c * p[1]]
+  let minX = Number.POSITIVE_INFINITY
+  let minZ = Number.POSITIVE_INFINITY
+  let maxX = Number.NEGATIVE_INFINITY
+  let maxZ = Number.NEGATIVE_INFINITY
+  for (const loop of footprintLoops) {
+    for (const p of loop) {
+      const [x, z] = toLocal(p)
+      if (x < minX) minX = x
+      if (x > maxX) maxX = x
+      if (z < minZ) minZ = z
+      if (z > maxZ) maxZ = z
+    }
+  }
+  if (!Number.isFinite(minX)) return []
+  const midX = (minX + maxX) / 2
+  const midZ = (minZ + maxZ) / 2
+  const casts: { from: Pt; dir: Pt }[] = [
+    { from: [midX, minZ], dir: [0, -1] },
+    { from: [midX, maxZ], dir: [0, 1] },
+    { from: [minX, midZ], dir: [-1, 0] },
+    { from: [maxX, midZ], dir: [1, 0] },
+  ]
+  const sides: YardSide[] = ['north', 'east', 'south', 'west']
+  const out: YardDimension[] = []
+  for (const cast of casts) {
+    const from = toWorld(cast.from)
+    const [dx, dy] = toWorld(cast.dir)
+    const hit = rayToPolygon(lot, from, dx, dy)
+    if (!hit) continue
+    // heading of the cast: plan up (−y) is north, +x east
+    const heading = ((Math.atan2(dx, -dy) * 180) / Math.PI + 360) % 360
+    const side = sides[Math.round(heading / 90) % 4] as YardSide
+    out.push({ side, from, to: hit.point, distance: hit.distance })
+  }
+  return out
+}
+
+/** Even-odd point-in-polygon. */
+export function pointInPolygon(points: readonly Pt[], x: number, y: number): boolean {
+  let inside = false
+  for (let i = 0, j = points.length - 1; i < points.length; j = i++) {
+    const a = points[i] as Pt
+    const b = points[j] as Pt
+    if (a[1] > y !== b[1] > y && x < ((b[0] - a[0]) * (y - a[1])) / (b[1] - a[1]) + a[0]) {
+      inside = !inside
+    }
+  }
+  return inside
+}
+
+/** True when every corner of `bounds` is inside `lot`. */
+export function boundsInsidePolygon(lot: readonly Pt[], bounds: Bounds): boolean {
+  if (lot.length < 3) return false
+  const corners: Pt[] = [
+    [bounds.minX, bounds.minY],
+    [bounds.maxX, bounds.minY],
+    [bounds.maxX, bounds.maxY],
+    [bounds.minX, bounds.maxY],
+  ]
+  return corners.every((c) => pointInPolygon(lot, c[0], c[1]))
+}
+
+export const METRES_PER_FOOT = 0.3048
+
+/** `24'-6"` — the notation a US site plan uses for yard dimensions. */
+export function formatFeetInches(metres: number): string {
+  const totalInches = Math.round((metres / METRES_PER_FOOT) * 12)
+  const feet = Math.floor(totalInches / 12)
+  const inches = totalInches % 12
+  return inches === 0 ? `${feet}'-0"` : `${feet}'-${inches}"`
+}

package/src/lib/floorplan/site-plan/index.ts

@@ -0,0 +1,71 @@
+export {
+  buildingRecentreOffset,
+  buildSitePlanDrawing,
+  describeSiteEdges,
+  levelFootprintLoops,
+  type SitePlanDrawing,
+  type SitePlanEdge,
+} from './build-site-plan-drawing'
+export {
+  hasSitePlanContributors,
+  registerSitePlanContributor,
+  type SitePlanContributor,
+  type SitePlanServicePoint,
+  type SitePlanServiceRole,
+  type SitePlanServices,
+  sitePlanContributions,
+  subscribeSitePlanContributors,
+} from './contributors'
+export {
+  computeSiteCoverage,
+  formatCoveragePercent,
+  formatSqFt,
+  type ImperviousRow,
+  type SiteCoverage,
+} from './coverage'
+export {
+  FloorplanDrawingTypeSwitch,
+  isSitePlanAvailable,
+  useSitePlanAvailable,
+} from './drawing-type-switch'
+export {
+  detectFrontEdgeFromRoads,
+  FRONT_EDGE_PARALLEL_DEG,
+  type FrontEdgeMatch,
+  type RoadCenterline,
+  streetCore,
+} from './front-edge'
+export {
+  type Bounds,
+  boundsInsidePolygon,
+  castYardDimensions,
+  castYardDimensionsOriented,
+  classifyEdges,
+  compassLabel,
+  edgeHeadingDeg,
+  edgeLength,
+  formatFeetInches,
+  METRES_PER_FOOT,
+  mostNorthFacingEdge,
+  outwardNormal,
+  type Pt,
+  pointInPolygon,
+  polygonArea,
+  polygonBounds,
+  polygonCentroid,
+  rayToPolygon,
+  resolveFrontEdge,
+  type SetbackInputs,
+  setbackEnvelope,
+  setbackForRole,
+  type YardDimension,
+  type YardSide,
+} from './geometry'
+export {
+  formatStreetName,
+  serviceEntranceOf,
+  streetEdgeNames,
+  UNNAMED_STREET,
+} from './site-annotations'
+export { flatworkKindOf, type OutdoorPart } from './site-parts'
+export { FloorplanSitePlanLayer } from './site-plan-layer'