@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/lot/clean-ring.ts

@@ -0,0 +1,217 @@
+/**
+ * Lot ring cleanup — a GIS parcel ring as the registry draws it, made fit
+ * for planning geometry (setbacks, the street edge, yard dimensions).
+ *
+ * What comes back from a parcel layer (seen live on the Land Park preset,
+ * 2026-09-06): the closing vertex repeated, points dropped along straight
+ * lines, and a curb-return CORNER drawn as nine ~1 m segments turning
+ * 8–12° each. Left alone, that ring breaks everything downstream: the
+ * street-facing "edge" the road detector picks is a 1 m sliver of the arc,
+ * the sliver takes the 20 ft front setback while the real 30 ft frontage
+ * beside it takes 5 ft, the offset lines cross and the setback envelope
+ * collapses to nothing — and the house lands at the origin, unplaced.
+ *
+ * Three passes, each pure and tested:
+ *   1. duplicates — consecutive vertices closer than `DUPLICATE_M` merge,
+ *      the closing repeat goes;
+ *   2. collinear — a vertex whose turn is under `COLLINEAR_DEG` goes;
+ *   3. arcs — a run of short edges (each ≤ `ARC_EDGE_MAX_M`, the run ≤
+ *      `ARC_RUN_MAX_M` long) between two longer edges that meet at
+ *      ≥ `ARC_MIN_TURN_DEG` is a rounded or chamfered corner: its vertices
+ *      are replaced by the corner the two long edges make when extended. A
+ *      surveyed plat calls that point the lot corner; the envelope drawn
+ *      from the squared edges sits inside the curved line by far more than
+ *      the rounding took away, so it is the conservative reading for
+ *      setbacks. The recorded lot area is never recomputed from it.
+ *
+ * Returns the cleaned ring with a count of what each pass removed, so the
+ * caller can say so in the parcel notes.
+ */
+import type { Pt } from '../floorplan/site-plan/geometry'
+
+export const DUPLICATE_M = 0.05
+export const COLLINEAR_DEG = 1.5
+/** A 10 ft corner cut (3.05 m) is a chamfer; a 15 ft one is a real side. */
+export const ARC_EDGE_MAX_M = 3.5
+export const ARC_RUN_MAX_M = 12
+export const ARC_MIN_TURN_DEG = 20
+
+export interface CleanRingResult {
+  points: Pt[]
+  removed: { duplicates: number; collinear: number; arcVertices: number; arcs: number }
+}
+
+const dist = (a: Pt, b: Pt): number => Math.hypot(b[0] - a[0], b[1] - a[1])
+
+const turnDeg = (a: Pt, b: Pt, c: Pt): number => {
+  const ux = b[0] - a[0]
+  const uy = b[1] - a[1]
+  const vx = c[0] - b[0]
+  const vy = c[1] - b[1]
+  const lu = Math.hypot(ux, uy)
+  const lv = Math.hypot(vx, vy)
+  if (lu < 1e-12 || lv < 1e-12) return 0
+  return (Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy) * 180) / Math.PI
+}
+
+/** Angle between two edge directions, degrees, unsigned. */
+const angleBetweenDeg = (a0: Pt, a1: Pt, b0: Pt, b1: Pt): number => {
+  const ux = a1[0] - a0[0]
+  const uy = a1[1] - a0[1]
+  const vx = b1[0] - b0[0]
+  const vy = b1[1] - b0[1]
+  return Math.abs((Math.atan2(ux * vy - uy * vx, ux * vx + uy * vy) * 180) / Math.PI)
+}
+
+/** Pass 1: consecutive near-duplicates (and the closing repeat) merge. */
+export function dropDuplicateVertices(points: readonly Pt[], tol = DUPLICATE_M): Pt[] {
+  const out: Pt[] = []
+  for (const p of points) {
+    const last = out[out.length - 1]
+    if (last && dist(last, p) < tol) continue
+    out.push([p[0], p[1]])
+  }
+  while (out.length > 1 && dist(out[0] as Pt, out[out.length - 1] as Pt) < tol) out.pop()
+  return out
+}
+
+/** Pass 2: vertices that do not turn go. */
+export function mergeCollinearVertices(points: readonly Pt[], tolDeg = COLLINEAR_DEG): Pt[] {
+  let ring = points.map((p) => [p[0], p[1]] as Pt)
+  let changed = true
+  while (changed && ring.length > 3) {
+    changed = false
+    for (let i = 0; i < ring.length && ring.length > 3; i++) {
+      const n = ring.length
+      const a = ring[(i - 1 + n) % n] as Pt
+      const b = ring[i] as Pt
+      const c = ring[(i + 1) % n] as Pt
+      if (Math.abs(turnDeg(a, b, c)) < tolDeg) {
+        ring = ring.filter((_, k) => k !== i)
+        changed = true
+        i--
+      }
+    }
+  }
+  return ring
+}
+
+/** Intersection of the lines a0→a1 and b0→b1, or null when parallel. */
+function lineIntersection(a0: Pt, a1: Pt, b0: Pt, b1: Pt): Pt | null {
+  const dx1 = a1[0] - a0[0]
+  const dy1 = a1[1] - a0[1]
+  const dx2 = b1[0] - b0[0]
+  const dy2 = b1[1] - b0[1]
+  const denom = dx1 * dy2 - dy1 * dx2
+  if (Math.abs(denom) < 1e-9) return null
+  const t = ((b0[0] - a0[0]) * dy2 - (b0[1] - a0[1]) * dx2) / denom
+  return [a0[0] + dx1 * t, a0[1] + dy1 * t]
+}
+
+/**
+ * Pass 3: rounded / chamfered corners squared. A run is a maximal set of
+ * consecutive SHORT edges between two LONG edges; every vertex of the run
+ * (the point where the long edge before it ends, through the point where
+ * the long edge after it starts) is replaced by the long edges'
+ * intersection when the run is short, the long edges meet at a real angle,
+ * and the corner point lands near the run.
+ */
+export function squareCornerArcs(
+  points: readonly Pt[],
+  opts: { edgeMax?: number; runMax?: number; minTurnDeg?: number } = {},
+): { points: Pt[]; arcs: number; arcVertices: number } {
+  const edgeMax = opts.edgeMax ?? ARC_EDGE_MAX_M
+  const runMax = opts.runMax ?? ARC_RUN_MAX_M
+  const minTurn = opts.minTurnDeg ?? ARC_MIN_TURN_DEG
+  const ring = points.map((p) => [p[0], p[1]] as Pt)
+  const n = ring.length
+  const none = { points: ring, arcs: 0, arcVertices: 0 }
+  if (n < 4) return none
+
+  const at = (i: number) => ring[((i % n) + n) % n] as Pt
+  const short: boolean[] = []
+  for (let i = 0; i < n; i++) short.push(dist(at(i), at(i + 1)) <= edgeMax)
+  const start = short.indexOf(false)
+  if (start < 0) return none // every edge short: not a lot we can square
+
+  // Runs of short edges, as [first edge, last edge] in ring order.
+  const runs: [number, number][] = []
+  let k = 1
+  while (k <= n) {
+    const idx = (start + k) % n
+    if (!short[idx]) {
+      k++
+      continue
+    }
+    const first = idx
+    let last = idx
+    while (short[(last + 1) % n] && (last + 1) % n !== start) last = (last + 1) % n
+    runs.push([first, last])
+    k += ((last - first + n) % n) + 1
+  }
+
+  // Which vertices each qualifying run replaces, and with what.
+  const replaced = new Map<number, Pt | null>() // vertex → corner (first vertex) or null (dropped)
+  let arcs = 0
+  let arcVertices = 0
+  for (const [first, last] of runs) {
+    const before = (first - 1 + n) % n // long edge before the run
+    const after = (last + 1) % n // long edge after the run
+    if (short[before] || short[after]) continue
+    let runLen = 0
+    for (let e = first; ; e = (e + 1) % n) {
+      runLen += dist(at(e), at(e + 1))
+      if (e === last) break
+    }
+    if (runLen > runMax) continue
+    if (angleBetweenDeg(at(before), at(before + 1), at(after), at(after + 1)) < minTurn) continue
+    const corner = lineIntersection(at(before), at(before + 1), at(after), at(after + 1))
+    if (!corner) continue
+    if (dist(corner, at(first)) > runMax || dist(corner, at(after)) > runMax) continue
+    // vertices first .. after (inclusive) → the corner
+    const count = ((after - first + n) % n) + 1
+    for (let j = 0; j < count; j++) replaced.set((first + j) % n, j === 0 ? corner : null)
+    arcs++
+    arcVertices += count - 1
+  }
+  if (arcs === 0) return none
+
+  const out: Pt[] = []
+  for (let i = 0; i < n; i++) {
+    if (!replaced.has(i)) {
+      out.push(at(i))
+      continue
+    }
+    const corner = replaced.get(i)
+    if (corner) out.push(corner)
+  }
+  return { points: out, arcs, arcVertices }
+}
+
+/** All three passes. */
+export function cleanLotRing(points: readonly Pt[]): CleanRingResult {
+  const deduped = dropDuplicateVertices(points)
+  const duplicates = points.length - deduped.length
+  const merged = mergeCollinearVertices(deduped)
+  const squared = squareCornerArcs(merged)
+  const final = mergeCollinearVertices(squared.points)
+  const collinear = deduped.length - merged.length + (squared.points.length - final.length)
+  return {
+    points: final,
+    removed: { duplicates, collinear, arcVertices: squared.arcVertices, arcs: squared.arcs },
+  }
+}
+
+/** One sentence for the parcel notes, or '' when nothing was removed. */
+export function describeRingCleanup(before: number, result: CleanRingResult): string {
+  const r = result.removed
+  if (before === result.points.length) return ''
+  const parts = [
+    r.arcs > 0
+      ? `${r.arcs} rounded corner${r.arcs === 1 ? '' : 's'} squared (${r.arcVertices} arc vertices)`
+      : '',
+    r.collinear > 0 ? `${r.collinear} collinear point${r.collinear === 1 ? '' : 's'} merged` : '',
+    r.duplicates > 0 ? `${r.duplicates} duplicate${r.duplicates === 1 ? '' : 's'} dropped` : '',
+  ].filter(Boolean)
+  return `Lot ring simplified for planning: ${before} → ${result.points.length} vertices (${parts.join(', ')}); setbacks and the street edge use the simplified ring, the recorded lot area stands.`
+}

package/src/lib/lot/dossier.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from 'bun:test'
+import miami from './__fixtures__/map-dossier-miami-shores.json'
+import stpete from './__fixtures__/map-dossier-stpete.json'
+import { cleanLotRing } from './clean-ring'
+import {
+  answered,
+  contourLinesFromDossier,
+  type Dossier,
+  describeDossier,
+  detectFrontEdgeFromFrontage,
+  frontageSegmentsMetres,
+  type ParcelData,
+  parcelRingMetres,
+  planPointFromLngLat,
+  setbacksFromZoning,
+  siteFactsFromDossier,
+  type ZoningData,
+} from './dossier'
+import { DEFAULT_SETBACKS_M, type ParcelResolveData, sitePatchFromParcel } from './lot-patch'
+
+/**
+ * Two RECORDED Pascal Map dossiers (2026-09-07, `__fixtures__/map-dossier-*.json`):
+ * St Petersburg — every section answers, a 13-acre block with three
+ * frontage segments, zone AE, wind 150 mph, DC-3 form-based zoning;
+ * Miami Shores — no parcel plane, but flood / utilities / soils answer.
+ */
+const STPETE = stpete as unknown as Dossier
+const MIAMI = miami as unknown as Dossier
+
+describe('projection', () => {
+  test('a point east and south of the origin reads +x, +z in metres', () => {
+    const p = planPointFromLngLat([-82.6, 27.7], [-82.599, 27.699])
+    expect(p[0]).toBeGreaterThan(0)
+    expect(p[1]).toBeGreaterThan(0)
+    // 0.001° of latitude ≈ 364 ft ≈ 111 m
+    expect(p[1]).toBeCloseTo(0.001 * 364000 * 0.3048, 3)
+  })
+})
+
+describe('the St Petersburg dossier', () => {
+  const parcel = answered<ParcelData>(STPETE, 'parcel')!
+  const origin: [number, number] = [STPETE.point.lng, STPETE.point.lat]
+
+  test('the parcel ring: the largest polygon, in plan metres, about 13 acres', () => {
+    const ring = parcelRingMetres(parcel, origin)
+    expect(ring.length).toBeGreaterThanOrEqual(4)
+    let a = 0
+    for (let i = 0; i < ring.length; i++) {
+      const p = ring[i]!
+      const q = ring[(i + 1) % ring.length]!
+      a += p[0] * q[1] - q[0] * p[1]
+    }
+    expect(Math.abs(a) / 2).toBeCloseTo(53022, -3) // area_m2 on the record, within a few hundred m²
+  })
+
+  test('the frontage: three street edges of the fabric become segments; the longest fronting edge of the cleaned ring is the front', () => {
+    const segments = frontageSegmentsMetres(parcel, origin)
+    expect(segments.length).toBeGreaterThanOrEqual(3)
+    const ring = cleanLotRing(parcelRingMetres(parcel, origin)).points
+    const match = detectFrontEdgeFromFrontage(ring, segments)
+    expect(match).not.toBeNull()
+    expect(match!.frontingEdges).toBeGreaterThanOrEqual(2) // a block: streets on more than one side
+    // the front is the longest fronting edge
+    for (let i = 0; i < ring.length; i++) {
+      const a = ring[i]!
+      const b = ring[(i + 1) % ring.length]!
+      const len = Math.hypot(b[0] - a[0], b[1] - a[1])
+      if (i !== match!.index && len > match!.lengthM + 1e-6) {
+        const other = detectFrontEdgeFromFrontage([a, b, [b[0] + 1, b[1] + 1]], segments)
+        // a longer edge exists only if it does not front
+        expect(other === null || other.index !== 0).toBe(true)
+      }
+    }
+  })
+
+  test('DC-3 form-based zoning: null setbacks stay null, the note is the code text', () => {
+    const zoning = answered<ZoningData>(STPETE, 'zoning')!
+    expect(zoning.district).toBe('DC-3')
+    expect(setbacksFromZoning(zoning)).toBeNull()
+    expect(zoning.dimensional_note).toContain('FAR')
+    expect(setbacksFromZoning({ setbacks: { front_ft: 25, side_ft: 7.5, rear_ft: 20 } })).toEqual({
+      front: 25 * 0.3048,
+      side: 7.5 * 0.3048,
+      rear: 20 * 0.3048,
+    })
+  })
+
+  test('the facts the site keeps: every section status, the flood / code basis / zoning / utilities data, no geometry, no neighbours', () => {
+    const facts = siteFactsFromDossier(STPETE)
+    expect(facts.provider).toBe('Pascal Map')
+    expect(facts.sections.parcel?.status).toBe('available')
+    expect(facts.sections.permits?.status).toBe('not_covered')
+    expect((facts.flood as { zone_at_point?: { zone?: string } }).zone_at_point?.zone).toBe('AE')
+    expect((facts.codeBasis as { wind_speed_mph?: number }).wind_speed_mph).toBe(150)
+    expect((facts.zoning as { district?: string }).district).toBe('DC-3')
+    expect((facts.utilities as { wastewater?: string }).wastewater).toBe('sewer')
+    expect(JSON.stringify(facts)).not.toContain('"geometry"')
+    expect((facts.parcel as Record<string, unknown>).adjacent_parcels).toBeUndefined()
+    expect(describeDossier(STPETE)).toContain('sections answered')
+  })
+
+  test('the lot patch: the frontage edge beats the road match; the facts ride the site', () => {
+    const ring = parcelRingMetres(parcel, origin)
+    const data: ParcelResolveData = {
+      ok: true,
+      polygonM: ring.map((p) => [p[0], p[1]]),
+      originLngLat: origin,
+      state: 'FL',
+      geocodedBy: 'pascal-map',
+    }
+    const segments = frontageSegmentsMetres(parcel, origin)
+    const facts = siteFactsFromDossier(STPETE)
+    const out = sitePatchFromParcel(
+      null,
+      { address: '501 5th Ave N' },
+      data,
+      null,
+      '2026-09-07T00:00:00Z',
+      {
+        frontageSegmentsM: segments,
+        setbacks: null,
+        dimensionalNote: 'No minimum lot area',
+        zone: 'DC-3',
+        facts,
+        line: 'Pascal Map: 12 sections answered',
+      },
+    )!
+    expect(out.summary.frontEdgeSource).toBe('frontage')
+    expect(out.summary.frontEdge).not.toBeNull()
+    expect(out.patch.frontEdge).toBe(out.summary.frontEdge!)
+    expect(out.patch.zone).toBe('DC-3')
+    // a conditional rule: the default stands and the code text is noted
+    expect(out.patch.setbacks).toEqual(DEFAULT_SETBACKS_M)
+    expect(out.summary.notes.some((n) => n.includes('Zoning condition'))).toBe(true)
+    expect(out.patch.dossier?.provider).toBe('Pascal Map')
+    // numbers from the code win over the default
+    const zoned = sitePatchFromParcel(null, { address: 'x' }, data, null, '2026-09-07T00:00:00Z', {
+      setbacks: { front: 7.62, side: 2.286, rear: 6.096 },
+      setbacksSource: 'Zoning R-1 — Section 17.212 — via Pascal Map',
+      facts,
+      line: '',
+    })!
+    expect(zoned.patch.setbacks).toEqual({ front: 7.62, side: 2.286, rear: 6.096 })
+    expect(zoned.patch.setbacksSource).toContain('Section 17.212')
+    expect(zoned.summary.setbacksDefaulted).toBe(false)
+  })
+})
+
+describe('the Miami Shores dossier (no parcel plane)', () => {
+  test('parcel not covered, flood and utilities answer; the ring is empty', () => {
+    expect(answered(MIAMI, 'parcel')).toBeNull()
+    expect(MIAMI.layers.parcel?.status).toBe('not_covered')
+    expect(
+      parcelRingMetres(answered<ParcelData>(MIAMI, 'parcel'), [MIAMI.point.lng, MIAMI.point.lat]),
+    ).toEqual([])
+    const facts = siteFactsFromDossier(MIAMI)
+    expect(facts.parcel).toBeUndefined()
+    expect((facts.flood as { zone_at_point?: { zone?: string } }).zone_at_point?.zone).toBe('X')
+    expect(
+      ((facts.utilities as { electric_providers?: { name: string }[] }).electric_providers ?? [])[0]
+        ?.name,
+    ).toContain('FLORIDA POWER')
+    expect(describeDossier(MIAMI)).toContain('parcel')
+  })
+})
+
+describe('the 3DEP contour lines', () => {
+  test('St Petersburg: 129 one-foot lines projected into the site frame, thinned, NAVD88', () => {
+    const origin: [number, number] = [STPETE.point.lng, STPETE.point.lat]
+    const lines = contourLinesFromDossier(STPETE, origin)
+    expect(lines).not.toBeNull()
+    expect(lines!.datum).toBe('NAVD88')
+    expect(lines!.intervalFt).toBe(1)
+    expect(lines!.source).toContain('3DEP')
+    expect(lines!.lines.length).toBe(129)
+    const elevations = new Set(lines!.lines.map((l) => l.elevationFt))
+    expect(Math.min(...elevations)).toBe(0)
+    expect(Math.max(...elevations)).toBeCloseTo(20, 0)
+    // every point within the parcel bbox's reach of the origin (a 13-acre block: a few hundred metres)
+    let n = 0
+    for (const l of lines!.lines) {
+      expect(l.points.length).toBeGreaterThanOrEqual(2)
+      for (const p of l.points) {
+        expect(Math.hypot(p[0], p[1])).toBeLessThan(600)
+        n++
+      }
+      for (let i = 1; i < l.points.length; i++) {
+        const a = l.points[i - 1]!
+        const b = l.points[i]!
+        expect(Math.hypot(a[0] - b[0], a[1] - b[1])).toBeGreaterThanOrEqual(0.3 - 1e-9)
+      }
+    }
+    // thinned below the 3501 recorded vertices
+    expect(n).toBeLessThan(3501)
+    expect(n).toBeGreaterThan(1000)
+  })
+
+  test('Miami Shores: the section answers without lines → null', () => {
+    const origin: [number, number] = [MIAMI.point.lng, MIAMI.point.lat]
+    expect(contourLinesFromDossier(MIAMI, origin)).toBeNull()
+  })
+})