@pascal-app/editor 1.0.3 → 1.0.5

package/src/lib/floorplan/site-plan/contours.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'bun:test'
+import { createTerrainField, quantize, terrainContours } from '@pascal-app/core'
+
+/** A 20 × 20 m field at 1 m spacing rising 2 m from x = −10 to x = +10 (a plane). */
+function ramp() {
+  const field = createTerrainField({ origin: [-10, -10], spacing: 1, cols: 21, rows: 21 })
+  const heights = new Int16Array(field.heights)
+  for (let row = 0; row < 21; row++)
+    for (let col = 0; col < 21; col++) heights[row * 21 + col] = quantize(field, (col / 20) * 2)
+  return { ...field, heights }
+}
+
+const LOT: [number, number][] = [
+  [-8, -8],
+  [8, -8],
+  [8, 8],
+  [-8, 8],
+]
+
+describe('terrainContours', () => {
+  test('a plane rising along x: straight north–south lines at every interval, clipped to the lot, every fifth an index', () => {
+    const contours = terrainContours(ramp(), 0.3048, LOT) // 1 ft interval on a 2 m rise → levels 0.30 … 1.83
+    expect(contours.length).toBeGreaterThanOrEqual(5)
+    for (const c of contours) {
+      // a level line of a plane rising in x is a vertical line x = const
+      const xs = c.points.map((p) => p[0])
+      expect(Math.max(...xs) - Math.min(...xs)).toBeLessThan(1e-6)
+      expect(Math.abs(xs[0]! - (-10 + (c.levelM / 2) * 20))).toBeLessThan(1e-6)
+      // clipped to the lot: no point outside z ∈ [−8, 8] by more than a cell
+      for (const p of c.points) expect(Math.abs(p[1])).toBeLessThanOrEqual(9)
+    }
+    expect(contours.some((c) => c.index)).toBe(true)
+    // one polyline per level: the chaining joined the cell segments
+    const levels = new Set(contours.map((c) => c.levelM.toFixed(4)))
+    expect(levels.size).toBe(contours.length)
+  })
+
+  test('no interval, or flat ground, gives no lines', () => {
+    expect(terrainContours(ramp(), 0, LOT)).toEqual([])
+    const flat = createTerrainField({ origin: [-10, -10], spacing: 1, cols: 21, rows: 21 })
+    expect(terrainContours(flat, 0.3048, LOT)).toEqual([])
+  })
+})

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

@@ -0,0 +1,97 @@
+/**
+ * Site-plan contributors — how plugin packages put their own kinds on the
+ * site plan without the editor depending on them.
+ *
+ * The site-plan layer draws only what `buildSitePlanDrawing` returns (it
+ * replaces the registry layer, so `def.floorplan` is not consulted in site
+ * view). A plugin whose kinds live in SITE metres (utilities: poles, runs,
+ * service points) registers a contributor at bootstrap; its primitives are
+ * appended to every site-plan drawing, on screen and on sheets alike. A
+ * plugin that locates the house's utility services also passes `services`,
+ * and the site plan runs them schematically to the street.
+ */
+import type { AnyNodeId, FloorplanGeometry, SceneSnapshot } from '@pascal-app/core'
+
+export type SitePlanContributor = (
+  scene: SceneSnapshot,
+) => { primitives: FloorplanGeometry[] } | null
+
+export type SitePlanServiceRole = 'electric' | 'water' | 'sewer'
+
+/**
+ * Where one service leaves the house, in the storey's plan frame. A point
+ * hosted by a wall with no position of its own sits `wallT` along `wallId`.
+ */
+export type SitePlanServicePoint = {
+  role: SitePlanServiceRole | 'ac' | 'pole'
+  position: readonly [number, number, number]
+  wallId?: AnyNodeId
+  wallT?: number
+}
+
+export type SitePlanServices = {
+  /** The storey's service points; the first point of each role is drawn. */
+  points?: (scene: SceneSnapshot, levelId: AnyNodeId) => readonly SitePlanServicePoint[]
+  /** The storey's electric service entrance, when the plugin decides it. */
+  entrance?: (scene: SceneSnapshot, levelId: AnyNodeId) => 'overhead' | 'underground' | null
+  /** Services the plugin already draws as its own run, so the site plan does not route them. */
+  drawnRuns?: (scene: SceneSnapshot) => readonly SitePlanServiceRole[]
+}
+
+type Registration = { draw: SitePlanContributor | null; services?: SitePlanServices }
+
+const contributors = new Map<string, Registration>()
+const listeners = new Set<() => void>()
+
+export function registerSitePlanContributor(
+  key: string,
+  contributor: SitePlanContributor | null,
+  services?: SitePlanServices,
+): void {
+  contributors.set(key, { draw: contributor, services })
+  for (const listener of listeners) listener()
+}
+
+/** Whether any plugin has put its kinds on the site plan. */
+export function hasSitePlanContributors(): boolean {
+  return contributors.size > 0
+}
+
+export function subscribeSitePlanContributors(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function sitePlanContributions(scene: SceneSnapshot): FloorplanGeometry[] {
+  const out: FloorplanGeometry[] = []
+  for (const [key, { draw }] of contributors) {
+    if (!draw) continue
+    try {
+      const result = draw(scene)
+      if (result) out.push(...result.primitives)
+    } catch (error) {
+      if (typeof console !== 'undefined')
+        console.warn(`[site-plan] contributor ${key} failed`, error)
+    }
+  }
+  return out
+}
+
+/** Every registered `services` hook's answer, in registration order; a throwing hook is skipped. */
+export function sitePlanServiceAnswers<T>(
+  ask: (services: SitePlanServices) => T | null | undefined,
+): T[] {
+  const out: T[] = []
+  for (const [key, { services }] of contributors) {
+    if (!services) continue
+    try {
+      const answer = ask(services)
+      if (answer !== null && answer !== undefined) out.push(answer)
+    } catch (error) {
+      if (typeof console !== 'undefined') console.warn(`[site-plan] services ${key} failed`, error)
+    }
+  }
+  return out
+}

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

@@ -0,0 +1,230 @@
+/**
+ * Lot coverage and impervious surface — the ONE computation the site plan
+ * (A1.0) and the cover's PROJECT DATA both print, so the two sheets can never
+ * disagree again (QA 2026-09-23: the cover said 24.6 %, the site plan 45.6 %
+ * — the site plan had counted the house's own floor platform and garage pad
+ * as "porches" on top of the footprint).
+ *
+ * The two figures a Florida plans examiner asks for (Alachua County / the
+ * City of Gainesville ask for both on a new single-family site plan; the
+ * zoning district caps the first, the stormwater review reads the second):
+ *
+ *  BUILDING COVERAGE  the lot area under roofed structure: the building's
+ *                     footprint to the OUTSIDE FACE of its exterior walls —
+ *                     every storey at or above grade projected, the attached
+ *                     garage included — plus the roofed porches, patios and
+ *                     decks (a slab at least half under a roof outline).
+ *                     Eaves and the roof overhang are not counted.
+ *  IMPERVIOUS SURFACE building coverage plus the paving ON THE LOT (an apron
+ *                     drawn out into the right-of-way is not counted): the driveway, the
+ *                     walks, and the uncovered patios, landings and decks
+ *                     (a slatted deck over pervious ground is counted —
+ *                     the conservative reading; some jurisdictions exclude
+ *                     it, verify).
+ *
+ * Both are divided by the LOT AREA: the county parcel record when the lot
+ * drop-in resolved one (`site.parcel.lotAreaSqFt`), else the drawn lot
+ * polygon. Pure: reads a scene snapshot, touches no store.
+ */
+import { footprintOutline, levelFootprintLoops, type SceneSnapshot } from '@pascal-app/core'
+import { METRES_PER_FOOT, type Pt, pointInPolygon, polygonArea, polygonBounds } from './geometry'
+import {
+  aboveGradeLevels,
+  findBuilding,
+  findLowestLevel,
+  findSite,
+  type OutdoorPart,
+  outdoorParts,
+  roofOutlineRings,
+} from './site-parts'
+
+const SQFT_PER_SQM = 1 / (METRES_PER_FOOT * METRES_PER_FOOT)
+
+export type ImperviousRowKey = 'building' | 'porches' | 'driveway' | 'walks' | 'patios'
+
+export interface ImperviousRow {
+  key: ImperviousRowKey
+  label: string
+  sqFt: number
+  /** What the row holds, e.g. "2 covered: porch, rear deck". */
+  note: string
+}
+
+export interface SiteCoverage {
+  /** Lot area, SF, and where it came from; null without a lot. */
+  lotSqFt: number | null
+  lotSource: 'parcel' | 'polygon' | null
+  /** The building's footprint to the outside face of its walls (garage included), SF. */
+  buildingSqFt: number
+  /** Roofed porches, patios and decks, SF. */
+  coveredOutdoorSqFt: number
+  /** Building coverage = footprint + roofed porches, SF. */
+  buildingCoverageSqFt: number
+  /** Building coverage ÷ lot, 0–1; null without a lot or a building. */
+  buildingCoverageRatio: number | null
+  drivewaySqFt: number
+  walksSqFt: number
+  /** Uncovered patios, landings and decks, SF. */
+  openOutdoorSqFt: number
+  /** Everything impervious, SF. */
+  imperviousSqFt: number
+  imperviousRatio: number | null
+  /** The IMPERVIOUS AREA table's rows, in print order (total and % are the caller's). */
+  rows: ImperviousRow[]
+  /** One line each: what the two figures are measured to — printed with them. */
+  basis: { building: string; impervious: string; lot: string }
+  /** The parts, for the drawing: the walls' outline and every outdoor slab (site metres). */
+  outline: Pt[][]
+  parts: OutdoorPart[]
+}
+
+const sf = (m2: number) => m2 * SQFT_PER_SQM
+
+/**
+ * The part of a slab's area on the lot: a driveway apron drawn out into the
+ * right-of-way is the road authority's paving, not the lot's. Whole when
+ * every corner is on the lot, else sampled on a fine grid.
+ */
+function onLotArea(ring: readonly Pt[], lot: readonly Pt[]): number {
+  const area = polygonArea(ring)
+  if (lot.length < 3) return area
+  const c = ring.reduce<[number, number]>(
+    (s, p) => [s[0] + p[0] / ring.length, s[1] + p[1] / ring.length],
+    [0, 0],
+  )
+  // a corner ON the lot line (the generator's driveway mouth) counts as on the lot
+  const onLot = (p: Pt) =>
+    pointInPolygon(lot, p[0] + (c[0] - p[0]) * 1e-3, p[1] + (c[1] - p[1]) * 1e-3)
+  if (ring.every(onLot)) return area
+  const b = polygonBounds(ring)
+  const N = 24
+  let inside = 0
+  let kept = 0
+  for (let i = 0; i < N; i++) {
+    for (let j = 0; j < N; j++) {
+      const x = b.minX + ((i + 0.5) / N) * (b.maxX - b.minX)
+      const y = b.minY + ((j + 0.5) / N) * (b.maxY - b.minY)
+      if (!pointInPolygon(ring, x, y)) continue
+      inside++
+      if (pointInPolygon(lot, x, y)) kept++
+    }
+  }
+  return inside > 0 ? (area * kept) / inside : area
+}
+
+/** "12.3 %" — the one way both sheets print a ratio. */
+export function formatCoveragePercent(ratio: number | null): string {
+  return ratio === null ? '—' : `${(ratio * 100).toFixed(1)} %`
+}
+
+/** "2,739 SF" — the one way both sheets print an area. */
+export function formatSqFt(sqFt: number): string {
+  return `${Math.round(sqFt).toLocaleString('en-US')} SF`
+}
+
+export function computeSiteCoverage(scene: Pick<SceneSnapshot, 'nodes'>): SiteCoverage {
+  const snapshot = scene as SceneSnapshot
+  const site = findSite(snapshot)
+  const building = findBuilding(snapshot, site)
+  const ground = findLowestLevel(snapshot, building)
+  const storeys = aboveGradeLevels(snapshot, building)
+  const levels = storeys.length > 0 ? storeys : ground ? [ground] : []
+
+  // the footprint: every storey's wall bands, unioned, outer rings only
+  const loops = levels.flatMap((level) => levelFootprintLoops(snapshot.nodes, level, building))
+  const outline = loops.length > 0 ? footprintOutline(loops) : []
+  const buildingM2 = outline.reduce((s, ring) => s + polygonArea(ring), 0)
+
+  const roofs = levels.flatMap((level) => roofOutlineRings(snapshot, level, building))
+  const parts = outdoorParts(snapshot, ground, building, outline, roofs)
+  const lotRing = (site?.polygon?.points ?? []) as Pt[]
+  const sum = (list: readonly OutdoorPart[]) =>
+    list.reduce((s, p) => s + onLotArea(p.ring, lotRing), 0)
+  const porches = parts.filter((p) => p.kind !== 'driveway' && p.kind !== 'walk')
+  const covered = porches.filter((p) => p.covered)
+  const open = porches.filter((p) => !p.covered)
+  const driveway = parts.filter((p) => p.kind === 'driveway')
+  const walks = parts.filter((p) => p.kind === 'walk')
+
+  const lotPoly = lotRing
+  const parcelSqFt =
+    typeof site?.parcel?.lotAreaSqFt === 'number' && site.parcel.lotAreaSqFt > 0
+      ? site.parcel.lotAreaSqFt
+      : null
+  const polygonSqFt = lotPoly.length >= 3 ? sf(polygonArea(lotPoly)) : 0
+  const lotSqFt = parcelSqFt ?? (polygonSqFt > 0 ? polygonSqFt : null)
+  const lotSource = parcelSqFt !== null ? 'parcel' : polygonSqFt > 0 ? 'polygon' : null
+
+  const buildingSqFt = sf(buildingM2)
+  const coveredOutdoorSqFt = sf(sum(covered))
+  const buildingCoverageSqFt = buildingSqFt + coveredOutdoorSqFt
+  const drivewaySqFt = sf(sum(driveway))
+  const walksSqFt = sf(sum(walks))
+  const openOutdoorSqFt = sf(sum(open))
+  const imperviousSqFt = buildingCoverageSqFt + drivewaySqFt + walksSqFt + openOutdoorSqFt
+  const ratio = (x: number) =>
+    lotSqFt !== null && lotSqFt > 0 && buildingSqFt > 0 ? x / lotSqFt : null
+
+  const names = (list: readonly OutdoorPart[]) => list.map((p) => p.label.toLowerCase()).join(', ')
+  const rows: ImperviousRow[] = [
+    {
+      key: 'building',
+      label: 'BUILDING (INCL. GARAGE)',
+      sqFt: buildingSqFt,
+      note: 'outside face of the exterior walls',
+    },
+    {
+      key: 'porches',
+      label: 'COVERED PORCHES / PATIOS',
+      sqFt: coveredOutdoorSqFt,
+      note: covered.length > 0 ? names(covered) : 'none',
+    },
+    {
+      key: 'driveway',
+      label: 'DRIVEWAY',
+      sqFt: drivewaySqFt,
+      note: driveway.length > 0 ? 'concrete' : 'none drawn',
+    },
+    {
+      key: 'walks',
+      label: 'WALKS',
+      sqFt: walksSqFt,
+      note: walks.length > 0 ? 'concrete' : 'none drawn',
+    },
+    {
+      key: 'patios',
+      label: 'OPEN PATIOS / DECKS / LANDINGS',
+      sqFt: openOutdoorSqFt,
+      note: open.length > 0 ? names(open) : 'none',
+    },
+  ]
+
+  return {
+    lotSqFt,
+    lotSource,
+    buildingSqFt,
+    coveredOutdoorSqFt,
+    buildingCoverageSqFt,
+    buildingCoverageRatio: ratio(buildingCoverageSqFt),
+    drivewaySqFt,
+    walksSqFt,
+    openOutdoorSqFt,
+    imperviousSqFt,
+    imperviousRatio: ratio(imperviousSqFt),
+    rows,
+    basis: {
+      building:
+        'Building coverage is the roofed area: the footprint to the outside face of the exterior walls (garage included, every storey projected) plus the roofed porches and patios; eaves excluded.',
+      impervious:
+        'Impervious surface is the building coverage plus the driveway, walks and the open patios, landings and decks (decks counted — verify the local rule).',
+      lot:
+        lotSource === 'parcel'
+          ? 'Lot area is the county parcel record.'
+          : lotSource === 'polygon'
+            ? 'Lot area is the drawn lot polygon (not a survey).'
+            : 'No lot area.',
+    },
+    outline,
+    parts,
+  }
+}

package/src/lib/floorplan/site-plan/drawing-type-switch.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'bun:test'
+import { isSitePlanAvailable } from './drawing-type-switch'
+
+describe('isSitePlanAvailable', () => {
+  test('a site with neither a parcel nor setbacks has no site plan', () => {
+    expect(isSitePlanAvailable(null, false)).toBe(false)
+    expect(isSitePlanAvailable({}, false)).toBe(false)
+  })
+
+  test('a resolved lot or a contributing plugin offers it', () => {
+    expect(isSitePlanAvailable({ parcel: { apn: '06075' } }, false)).toBe(true)
+    expect(isSitePlanAvailable({ setbacks: { front: 6, side: 1.5, rear: 3 } }, false)).toBe(true)
+    expect(isSitePlanAvailable({}, true)).toBe(true)
+  })
+})

package/src/lib/floorplan/site-plan/drawing-type-switch.tsx

@@ -0,0 +1,86 @@
+'use client'
+
+import { type SiteNode, useScene } from '@pascal-app/core'
+import { useEffect, useSyncExternalStore } from 'react'
+import useDrawingView, { EDITOR_DRAWING_TYPE_OPTIONS } from '../../../store/use-drawing-view'
+import { cn } from '../../utils'
+import { hasSitePlanContributors, subscribeSitePlanContributors } from './contributors'
+
+/**
+ * The site plan only has something to draw for a resolved lot (a parcel or
+ * setbacks on the site) or when a plugin contributes site-plan content; every
+ * other scene would get the default 30 m square.
+ */
+export function isSitePlanAvailable(
+  site: Pick<SiteNode, 'parcel' | 'setbacks'> | null,
+  pluginContributes: boolean,
+): boolean {
+  return pluginContributes || Boolean(site?.parcel || site?.setbacks)
+}
+
+export function useSitePlanAvailable(): boolean {
+  const pluginContributes = useSyncExternalStore(
+    subscribeSitePlanContributors,
+    hasSitePlanContributors,
+    hasSitePlanContributors,
+  )
+  const siteHasLot = useScene((state) => {
+    for (const id of state.rootNodeIds) {
+      const node = state.nodes[id]
+      if (node?.type === 'site') return isSitePlanAvailable(node as SiteNode, false)
+    }
+    return false
+  })
+  return pluginContributes || siteHasLot
+}
+
+/**
+ * Floor plan ⇄ Site plan switch for the 2D editor.
+ *
+ * Sits with the other floating plan controls in the floor-plan viewport
+ * (bottom-left, beside the compass). Theme tokens only. Hidden, and a
+ * persisted site-plan choice reset to the floor plan, when the scene has no
+ * site plan to show.
+ */
+export function FloorplanDrawingTypeSwitch({ className }: { className?: string }) {
+  const drawingType = useDrawingView((s) => s.drawingType)
+  const setDrawingType = useDrawingView((s) => s.setDrawingType)
+  const available = useSitePlanAvailable()
+
+  useEffect(() => {
+    if (!available && drawingType === 'site-plan') setDrawingType('floor-plan')
+  }, [available, drawingType, setDrawingType])
+
+  if (!available) return null
+
+  return (
+    <div
+      className={cn(
+        'pointer-events-auto absolute bottom-3 left-14 z-30 flex items-center gap-0.5 rounded-full border border-border bg-card/90 p-0.5 shadow-sm backdrop-blur-md',
+        className,
+      )}
+    >
+      {EDITOR_DRAWING_TYPE_OPTIONS.map((option) => (
+        <button
+          aria-pressed={drawingType === option.id}
+          className={cn(
+            'rounded-full px-2.5 py-1 font-medium text-xs transition',
+            drawingType === option.id
+              ? 'bg-primary text-primary-foreground'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+          key={option.id}
+          onClick={(event) => {
+            event.preventDefault()
+            event.stopPropagation()
+            setDrawingType(option.id)
+          }}
+          onPointerDown={(event) => event.stopPropagation()}
+          type="button"
+        >
+          {option.label}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/lib/floorplan/site-plan/front-edge.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test'
+import { detectFrontEdgeFromRoads, streetCore } from './front-edge'
+import type { Pt } from './geometry'
+
+// 20 m × 30 m lot centred on the origin, y south. Edge 0 = north side,
+// 1 = east, 2 = south, 3 = west.
+const LOT: Pt[] = [
+  [-10, -15],
+  [10, -15],
+  [10, 15],
+  [-10, 15],
+]
+const road = (name: string, ...pts: Pt[]) => ({ name, centerline: pts })
+
+describe('streetCore', () => {
+  test('drops the number, the direction and the suffix', () => {
+    expect(streetCore('2600 Castro Way')).toBe('castro')
+    expect(streetCore('S Castro')).toBe('castro')
+    expect(streetCore('W Cass St.')).toBe('cass')
+    expect(streetCore('1200 W Cass St')).toBe('cass')
+    expect(streetCore('North Troy Street')).toBe('troy')
+    // OSM spells the quadrant out
+    expect(streetCore('Northeast 109th Street')).toBe('109th')
+    expect(streetCore('1247 NE 109th St')).toBe('109th')
+    expect(streetCore('')).toBe('')
+    expect(streetCore(null)).toBe('')
+  })
+})
+
+describe('detectFrontEdgeFromRoads', () => {
+  test('the nearest parallel street on the outside picks its edge', () => {
+    const roads = [road('Castro Way', [-60, -25], [60, -25])]
+    const m = detectFrontEdgeFromRoads(LOT, roads)
+    expect(m?.index).toBe(0)
+    expect(m?.name).toBe('Castro Way')
+    expect(m?.distance).toBeCloseTo(10, 9)
+    expect(m?.named).toBe(false)
+  })
+
+  test('a road perpendicular to an edge never fronts it', () => {
+    // runs north-south past the middle of the north edge, 25 m out
+    const roads = [road('Stab St', [0, -60], [0, -25])]
+    expect(detectFrontEdgeFromRoads(LOT, roads)).toBeNull()
+  })
+
+  test('a road through the lot (inside the edge) is rejected', () => {
+    const roads = [road('Driveway', [-60, -5], [60, -5])]
+    expect(detectFrontEdgeFromRoads(LOT, roads)).toBeNull()
+  })
+
+  test('corner lot: the addressed street wins over a closer cross street', () => {
+    const roads = [
+      road('Castro Way', [-60, -30], [60, -30]), // north, 15 m off
+      road('Elm St', [18, -60], [18, 60]), // east, 8 m off — closer
+    ]
+    expect(detectFrontEdgeFromRoads(LOT, roads)?.index).toBe(1) // closest wins with no address
+    const named = detectFrontEdgeFromRoads(LOT, roads, '2600 Castro Way')
+    expect(named?.index).toBe(0)
+    expect(named?.named).toBe(true)
+    // an address on a street that is not mapped falls back to the closest
+    expect(detectFrontEdgeFromRoads(LOT, roads, '9 Nowhere Ln')?.index).toBe(1)
+  })
+
+  test('through lot: a street of the same number but another type is not the addressed street', () => {
+    const roads = [
+      road('Northwest 34th Terrace', [-18, -60], [-18, 60]), // west, 8 m off — closer
+      road('Northwest 34th Street', [25, -60], [25, 60]), // east, 15 m off
+    ]
+    const m = detectFrontEdgeFromRoads(LOT, roads, '4121 NW 34th St')
+    expect(m?.index).toBe(1)
+    expect(m?.name).toBe('Northwest 34th Street')
+    expect(m?.named).toBe(true)
+    expect(m?.streetNames).toEqual({ '1': 'Northwest 34th Street', '3': 'Northwest 34th Terrace' })
+    // addressed on the Terrace, the Terrace fronts it
+    expect(detectFrontEdgeFromRoads(LOT, roads, '4120 NW 34th Ter')?.index).toBe(3)
+  })
+
+  test('a bent road counts by its nearest segment; slight skew within 30° passes', () => {
+    const roads = [road('Bend Rd', [-80, -40], [-30, -26], [30, -24], [80, -40])]
+    expect(detectFrontEdgeFromRoads(LOT, roads)?.index).toBe(0)
+  })
+
+  test('winding does not matter', () => {
+    const cw = [...LOT].reverse() as Pt[]
+    const roads = [road('Castro Way', [-60, -25], [60, -25])]
+    const m = detectFrontEdgeFromRoads(cw, roads)
+    // reversed ring: the north edge is now points[2] → points[3]
+    expect(m?.index).toBe(2)
+  })
+
+  test('no roads, no answer', () => {
+    expect(detectFrontEdgeFromRoads(LOT, [])).toBeNull()
+    expect(
+      detectFrontEdgeFromRoads(
+        [
+          [0, 0],
+          [1, 0],
+        ],
+        [road('x', [0, -5], [1, -5])],
+      ),
+    ).toBeNull()
+  })
+})