@pascal-app/editor 1.0.3 → 1.0.4

package/src/lib/lot/lot-patch.ts

@@ -0,0 +1,394 @@
+/**
+ * Lot drop-in — the PURE half. Given the parcel service's answer and the
+ * mapped roads, compute the site node patch and a summary of what was
+ * decided (front edge, setbacks, notes). No store, no network, so every
+ * rule here is unit-tested; `drop-in.ts` does the fetching and writing.
+ *
+ * Rules:
+ * - The lot ring, address, parcel provenance and zoning come straight from
+ *   the parcel `resolve` answer; a new ring invalidates any front edge picked on
+ *   the old one.
+ * - The FRONT edge is the lot edge the real street fronts
+ *   (`detectFrontEdgeFromRoads`: parallel, outside, nearest, addressed
+ *   street wins on a corner). No road data → left undefined, which the site
+ *   plan resolves to the most north-facing edge, and the notes say so.
+ * - With the parcel fabric's frontage (Pascal Map), the front is the fronting
+ *   edge on the addressed street (`frontageFront`), else the longest fronting
+ *   edge; the note says which rule decided.
+ * - Setbacks: when the site has none, the planning defaults
+ *   (`DEFAULT_SETBACKS_FT` — front 20 ft, side 5 ft, rear 15 ft) are
+ *   written with a `setbacksSource` that says they are defaults. Existing
+ *   setbacks are never overwritten.
+ * - `northRotation` is 0: the parcel frame is x east / z south, so plan up
+ *   is true north.
+ */
+import type { SiteNode, SiteSetbacks } from '@pascal-app/core'
+import {
+  detectFrontEdgeFromRoads,
+  type FrontEdgeMatch,
+  type RoadCenterline,
+} from '../floorplan/site-plan/front-edge'
+import { edgeLength, METRES_PER_FOOT, type Pt } from '../floorplan/site-plan/geometry'
+import { sameStreet } from '../floorplan/site-plan/street-name'
+import { cleanLotRing, describeRingCleanup } from './clean-ring'
+import { detectFrontEdgeFromFrontage, type FrontageMatch } from './dossier'
+
+export const DEFAULT_SETBACKS_FT = { front: 20, side: 5, rear: 15 } as const
+export const DEFAULT_SETBACKS_M: SiteSetbacks = {
+  front: DEFAULT_SETBACKS_FT.front * METRES_PER_FOOT,
+  side: DEFAULT_SETBACKS_FT.side * METRES_PER_FOOT,
+  rear: DEFAULT_SETBACKS_FT.rear * METRES_PER_FOOT,
+}
+export const DEFAULT_SETBACKS_SOURCE =
+  'Planning defaults (front 20 ft, side 5 ft, rear 15 ft; typical single-family yards) — confirm with the zoning district.'
+
+/** OSM highway classes a house can front: streets, not alleys, driveways or sidewalks. */
+export const STREET_CLASSES: ReadonlySet<string> = new Set([
+  'motorway',
+  'trunk',
+  'primary',
+  'secondary',
+  'tertiary',
+  'residential',
+  'living_street',
+  'unclassified',
+])
+
+/** The parcel provider's `resolve` answer (the fields the drop-in reads). */
+export interface ParcelResolveData {
+  ok: boolean
+  error?: string
+  apn?: string
+  county?: string
+  state?: string
+  zip?: string
+  zoning?: string
+  lotAreaSqFt?: number
+  originLngLat?: [number, number]
+  geocodedBy?: string
+  matchPrecision?: string
+  notes?: string[]
+  polygonM?: [number, number][]
+  address?: { street?: string; city?: string; state?: string; zip?: string } | null
+}
+
+/** A road from the parcel provider's `roads` (centerline in the lot's frame, metres). */
+export interface LotRoad extends RoadCenterline {
+  id?: string
+  klass?: string
+  widthM?: number
+}
+
+/** What the user typed or picked. Coordinates skip geocoding when present. */
+export interface DropInInput {
+  address?: string
+  latitude?: number
+  longitude?: number
+  state?: string
+  street?: string
+  city?: string
+  zip?: string
+}
+
+/**
+ * What the Pascal Map dossier adds to a lot patch (lot drop-in, dossier.ts):
+ * the frontage segments the front edge is read from, the zoning setbacks
+ * with their citation, and the facts the site keeps for the sheets.
+ */
+export interface DossierExtras {
+  /** Frontage segments in plan metres — the lot edges that touch no neighbour. */
+  frontageSegmentsM?: readonly [readonly [number, number], readonly [number, number]][]
+  /** Zoning setbacks, metres — null when the code's rule is conditional. */
+  setbacks?: { front: number; side: number; rear: number } | null
+  setbacksSource?: string
+  /** The code's verbatim condition when a number cannot say it. */
+  dimensionalNote?: string | null
+  zone?: string
+  /** The geometry-free record the site node keeps. */
+  facts: SiteNode['dossier']
+  /** One status line, e.g. "Pascal Map: 9 sections answered (parcel not here)". */
+  line: string
+}
+
+export interface LotSummary {
+  apn: string
+  county: string
+  state: string
+  lotAreaSqFt: number
+  /** The street-facing edge index, or null when the north-facing fallback stands. */
+  frontEdge: number | null
+  frontStreet: string | null
+  frontEdgeSource: string
+  /** How many lot edges front a street / water per the parcel fabric (corner lots ≥ 2); absent without frontage. */
+  frontingEdges?: number
+  /** The dossier's own status line, when one was read. */
+  dossierLine?: string
+  setbacksDefaulted: boolean
+  roadsFound: number
+  notes: string[]
+}
+
+/** A trailing "ST zip" (US) or "STATE postcode" (AU), optionally after the city in the same part. */
+const STATE_ZIP_TAIL = /^(?:(.*?)\s+)?([A-Z]{2}|NSW|VIC|QLD|TAS|ACT)(?:\s+(\d{4,5}(?:-\d{4})?))?$/i
+const COUNTRY_PART = /^(usa?|u\.s\.a?\.?|united states(?: of america)?|australia)$/i
+
+/**
+ * The typed "street, city, ST zip" split into its parts — what the address
+ * says when the resolver answered no situs line (the parcel route never
+ * does). Without a comma it is all street.
+ */
+export function splitTypedAddress(typed: string | undefined): {
+  street?: string
+  city?: string
+  state?: string
+  zip?: string
+} {
+  const parts = String(typed ?? '')
+    .split(',')
+    .map((p) => p.trim())
+    .filter(Boolean)
+  if (parts.length > 1 && COUNTRY_PART.test(parts[parts.length - 1] as string)) parts.pop()
+  if (parts.length === 0) return {}
+  if (parts.length === 1) return { street: parts[0] }
+  const tail = STATE_ZIP_TAIL.exec(parts[parts.length - 1] as string)
+  if (!tail) return { street: parts.slice(0, -1).join(', '), city: parts[parts.length - 1] }
+  const [, cityInTail, state, zip] = tail
+  const streetParts = cityInTail ? parts.slice(0, -1) : parts.slice(0, -2)
+  const city = cityInTail ?? (parts.length > 2 ? parts[parts.length - 2] : undefined)
+  return {
+    street: (streetParts.length > 0 ? streetParts : parts.slice(0, 1)).join(', '),
+    ...(city ? { city } : {}),
+    state: (state as string).toUpperCase(),
+    ...(zip ? { zip } : {}),
+  }
+}
+
+const streetOf = (input: DropInInput, data: ParcelResolveData): string | undefined =>
+  input.street ?? data.address?.street ?? splitTypedAddress(input.address).street
+
+/** The front-edge decision, as text for the parcel notes and the panel. */
+export function describeFrontEdge(match: FrontEdgeMatch | null, roadsFound: number): string {
+  if (match) {
+    const name = match.name ? `"${match.name}"` : 'an unnamed street'
+    return `Front edge ${match.index + 1}: fronts ${name} (OpenStreetMap${match.named ? ', the addressed street' : ', nearest street'}).`
+  }
+  return roadsFound > 0
+    ? 'Front edge: no mapped street fronts a lot edge — the most north-facing edge stands; pick the street side in the Site panel.'
+    : 'Front edge: no road data — the most north-facing edge stands; pick the street side in the Site panel.'
+}
+
+/**
+ * Under this share of the longest frontage the addressed street's fronting
+ * edge is a sliver of the lot (a corner cut, a flag's pole), not its face.
+ */
+export const ADDRESSED_FRONTAGE_MIN_SHARE = 0.5
+
+/**
+ * The front among the parcel fabric's fronting edges: the one on the
+ * addressed street (a corner or through lot is addressed on its front
+ * street) — `streetNames` are the mapped street along each edge — unless it
+ * is under half the longest frontage; else the longest. `rule` says which
+ * decided, for the note.
+ */
+export function frontageFront(
+  ring: readonly Pt[],
+  frontage: FrontageMatch,
+  streetNames: Readonly<Record<string, string>>,
+  addressStreet: string | null | undefined,
+): { index: number; name: string; named: boolean; rule: string } {
+  const nameOf = (i: number) => streetNames[String(i)] ?? ''
+  const addressed = frontage.edges
+    .filter((i) => sameStreet(addressStreet, nameOf(i)))
+    .sort((a, b) => edgeLength(ring, b) - edgeLength(ring, a))[0]
+  if (
+    addressed !== undefined &&
+    edgeLength(ring, addressed) >= frontage.lengthM * ADDRESSED_FRONTAGE_MIN_SHARE
+  )
+    return {
+      index: addressed,
+      name: nameOf(addressed),
+      named: true,
+      rule: "the addressed street's frontage",
+    }
+  const rule =
+    addressed !== undefined
+      ? `the longest frontage — the addressed street's edge ${addressed + 1} is ${edgeLength(ring, addressed).toFixed(1)} m, under half the longest ${frontage.lengthM.toFixed(1)} m`
+      : frontage.edges.length === 1
+        ? 'the only frontage'
+        : frontage.edges.some((i) => nameOf(i))
+          ? 'the longest frontage — no fronting street is the addressed street'
+          : 'the longest frontage — no mapped street names to match the address'
+  return { index: frontage.index, name: nameOf(frontage.index), named: false, rule }
+}
+
+/**
+ * The site patch for a resolved parcel. `null` when the answer has no usable
+ * ring. `now` stamps `parcel.resolvedAt` (injectable for tests).
+ */
+export function sitePatchFromParcel(
+  site: (Pick<SiteNode, 'setbacks' | 'zone'> & { metadata?: unknown }) | null | undefined,
+  input: DropInInput,
+  data: ParcelResolveData,
+  roads: readonly LotRoad[] | null,
+  now: string = new Date().toISOString(),
+  dossier?: DossierExtras | null,
+): { patch: Partial<SiteNode>; summary: LotSummary } | null {
+  const raw = data.polygonM
+  if (!data.ok || !raw || raw.length < 3) return null
+  // The registry ring, made fit for planning (curb returns squared, surplus
+  // vertices gone) — see clean-ring.ts for why the raw ring cannot be used.
+  const cleaned = cleanLotRing(raw as readonly Pt[])
+  if (cleaned.points.length < 3) return null
+  const polygon = cleaned.points.map((p) => [p[0], p[1]] as [number, number])
+  const cleanupNote = describeRingCleanup(raw.length, cleaned)
+
+  const streets = (roads ?? []).filter((r) => !r.klass || STREET_CLASSES.has(r.klass))
+  const roadMatch = detectFrontEdgeFromRoads(
+    polygon as readonly Pt[],
+    streets,
+    streetOf(input, data),
+  )
+  // The parcel FABRIC beats the road match: the edges shared with no
+  // neighbour are the street (or water) edges, and the one on the addressed
+  // street (else the longest) is the front; the road match names the
+  // streets and stands in without a frontage; north-facing is the last resort.
+  const frontage = dossier?.frontageSegmentsM?.length
+    ? detectFrontEdgeFromFrontage(polygon as readonly Pt[], dossier.frontageSegmentsM)
+    : null
+  const fabricFront = frontage
+    ? frontageFront(
+        polygon as readonly Pt[],
+        frontage,
+        roadMatch?.streetNames ?? {},
+        streetOf(input, data),
+      )
+    : null
+  const match = fabricFront
+    ? { index: fabricFront.index, distance: 0, name: fabricFront.name, named: fabricFront.named }
+    : roadMatch
+  // (site-annotations reads the street back from this note up to its ')')
+  const frontNote =
+    frontage && fabricFront
+      ? `Front edge: edge ${fabricFront.index + 1} of the parcel fabric's frontage (${frontage.frontingEdges} fronting edge${frontage.frontingEdges === 1 ? '' : 's'}${fabricFront.name ? `, ${fabricFront.name}` : ''}) — ${fabricFront.rule} (Pascal Map).`
+      : describeFrontEdge(roadMatch, roads?.length ?? 0)
+
+  // Setbacks: the site's own stay; else the zoning code's numbers with
+  // their citation; else the default, with the code's condition printed
+  // beside it when the dossier carried one.
+  const zoned = !site?.setbacks && dossier?.setbacks ? dossier.setbacks : null
+  const setbacksDefaulted = !site?.setbacks && !zoned
+  const notes = [...(data.notes ?? []), ...(cleanupNote ? [cleanupNote] : []), frontNote]
+  if (zoned) notes.push(`Setbacks: ${dossier?.setbacksSource ?? 'zoning code via Pascal Map'}`)
+  if (setbacksDefaulted) notes.push(`Setbacks: ${DEFAULT_SETBACKS_SOURCE}`)
+  if (dossier?.dimensionalNote)
+    notes.push(`Zoning condition (verbatim, verify): ${dossier.dimensionalNote}`)
+  if (dossier?.line) notes.push(dossier.line)
+
+  // the street edges: the parcel fabric's frontage when it answered, else
+  // every edge a mapped road runs along
+  const streetEdges: number[] =
+    frontage && frontage.edges.length > 0 ? frontage.edges : (roadMatch?.streetEdges ?? [])
+  // the street each of those edges runs along, from the mapped roads (the
+  // site plan labels every street edge with its own street, not the address's)
+  const streetNames: Record<string, string> = {}
+  for (const i of streetEdges) {
+    const name = roadMatch?.streetNames?.[String(i)]
+    if (name) streetNames[String(i)] = name
+  }
+  const typed = splitTypedAddress(input.address)
+  const state = data.state || input.state || data.address?.state || typed.state
+  const patch: Partial<SiteNode> = {
+    address: {
+      street: streetOf(input, data),
+      city: input.city ?? data.address?.city ?? typed.city,
+      state,
+      zip: data.zip || input.zip || data.address?.zip || typed.zip,
+    },
+    parcel: {
+      apn: data.apn,
+      county: data.county,
+      layer: data.geocodedBy,
+      lotAreaSqFt: data.lotAreaSqFt,
+      notes,
+      originLngLat: data.originLngLat,
+      resolvedAt: now,
+      source: 'gis-parcel',
+      state,
+    },
+    polygon: { points: polygon, type: 'polygon' },
+    // A new lot invalidates a front-edge index picked on the old ring; the
+    // street decides the new one.
+    frontEdge: match ? match.index : undefined,
+    // every street edge (a corner lot has two or more) and the corner
+    // clear-vision triangle's leg (measured from the right of way) — the
+    // common residential 25 ft, verify locally
+    ...(streetEdges.length > 0 ? { streetEdges } : {}),
+    ...(streetEdges.length >= 2 ? { sightTriangleFt: 25 } : {}),
+    // The parcel frame is x east / z south: plan up is true north.
+    northRotation: 0,
+    ...((dossier?.zone ?? data.zoning) && !site?.zone
+      ? { zone: dossier?.zone ?? data.zoning }
+      : {}),
+    ...(zoned
+      ? {
+          setbacks: { ...zoned },
+          setbacksSource: dossier?.setbacksSource ?? 'zoning code via Pascal Map',
+        }
+      : setbacksDefaulted
+        ? { setbacks: { ...DEFAULT_SETBACKS_M }, setbacksSource: DEFAULT_SETBACKS_SOURCE }
+        : {}),
+    // always written: undefined clears the previous lot's dossier when this lookup read none
+    dossier: dossier?.facts,
+    // the street each street edge runs along (`metadata.streetNames`, by
+    // edge index) — the site plan names every street edge with its own
+    // street; the previous lot's names never carry over
+    metadata: (() => {
+      const { streetNames: _previous, ...rest } = (
+        site?.metadata && typeof site.metadata === 'object' && !Array.isArray(site.metadata)
+          ? site.metadata
+          : {}
+      ) as Record<string, unknown>
+      return Object.keys(streetNames).length > 0 ? { ...rest, streetNames } : rest
+    })(),
+  }
+
+  return {
+    patch,
+    summary: {
+      apn: data.apn ?? '',
+      county: data.county ?? '',
+      state: state ?? '',
+      lotAreaSqFt: data.lotAreaSqFt ?? 0,
+      frontEdge: match ? match.index : null,
+      frontStreet: match ? match.name || null : null,
+      frontEdgeSource: frontage
+        ? 'frontage'
+        : match
+          ? `osm:${match.name || 'unnamed'}`
+          : 'north-facing',
+      ...(frontage ? { frontingEdges: frontage.frontingEdges } : {}),
+      ...(dossier?.line ? { dossierLine: dossier.line } : {}),
+      setbacksDefaulted,
+      roadsFound: roads?.length ?? 0,
+      notes,
+    },
+  }
+}
+
+/** One line for a status row: "Lot set — APN 123 · 5,300 sq ft · Sacramento · fronts Castro Way · default setbacks". */
+export function describeLotSummary(summary: LotSummary, extra: string[] = []): string {
+  const parts = [
+    summary.apn ? `APN ${summary.apn}` : '',
+    summary.lotAreaSqFt ? `${Math.round(summary.lotAreaSqFt).toLocaleString('en-US')} sq ft` : '',
+    summary.county,
+    summary.frontEdge !== null
+      ? summary.frontEdgeSource === 'frontage'
+        ? `fronts ${summary.frontStreet || 'the street'} (edge ${summary.frontEdge + 1}, parcel frontage)`
+        : `fronts ${summary.frontStreet ?? 'an unnamed street'} (edge ${summary.frontEdge + 1})`
+      : 'front edge: most north-facing (no road match)',
+    summary.dossierLine ?? '',
+    summary.setbacksDefaulted ? 'setbacks defaulted 20 / 5 / 15 ft' : '',
+    ...extra,
+  ].filter(Boolean)
+  return `Lot set — ${parts.join(' · ')}`
+}

package/src/lib/lot/parcel-provider.ts

@@ -0,0 +1,43 @@
+/**
+ * The parcel service the lot tools read — injected by the host. The editor
+ * ships no parcel backend: a host that has one calls `setParcelProvider` at
+ * bootstrap, and until it does the address lookup is hidden and `dropInLot`
+ * answers that no service is available.
+ */
+import { useSyncExternalStore } from 'react'
+
+export type ParcelEndpoint = 'autocomplete' | 'resolve' | 'roads' | 'elevation' | 'dossier'
+
+/**
+ * Answers one parcel call with the endpoint's JSON. `body` is the request:
+ * `{ q }` for `autocomplete`, the posted JSON for the others.
+ */
+export type ParcelProvider = (
+  endpoint: ParcelEndpoint,
+  body: Record<string, unknown>,
+) => Promise<unknown>
+
+let provider: ParcelProvider | null = null
+const listeners = new Set<() => void>()
+
+export function setParcelProvider(next: ParcelProvider | null): void {
+  provider = next
+  for (const listener of listeners) listener()
+}
+
+export function getParcelProvider(): ParcelProvider | null {
+  return provider
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+export function useParcelProvider(): ParcelProvider | null {
+  return useSyncExternalStore(subscribe, getParcelProvider, getParcelProvider)
+}
+
+export const NO_PARCEL_SERVICE = 'No parcel service is available.'

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

@@ -0,0 +1,161 @@
+import { describe, expect, test } from 'bun:test'
+import { decodeTerrainField, heightAt } from '@pascal-app/core'
+import type { ParcelProvider } from './parcel-provider'
+import {
+  coarseHeightAt,
+  DEFAULT_GRID_N,
+  describeTerrainSample,
+  fieldFromSamples,
+  gridOver,
+  localMetresToLngLat,
+  MIN_RELIEF_M,
+  type Pt,
+  sampleLotTerrain,
+} from './terrain'
+
+// a 50 × 107 ft lot, x across, z into the lot
+const LOT: Pt[] = [
+  [0, 0],
+  [15.24, 0],
+  [15.24, 32.6],
+  [0, 32.6],
+]
+const ORIGIN: [number, number] = [-121.4944, 38.5816]
+const FT = 0.3048
+
+/** A fake elevation route: the ground is a plane, `slopeFtPerM` feet per metre of x, `base` ft, optional holes. */
+function fakeProvider(slopeFtPerM: number, base = 30, holeEvery = 0, fail = false): ParcelProvider {
+  return async (_endpoint, request) => {
+    const body = request as { points: { lat: number; lng: number }[] }
+    if (fail) return { ok: false, error: 'USGS down' }
+    // invert the projection the way the sampler projected: lng → x metres
+    const results = body.points.map((p, i) => {
+      const xM = (p.lng - ORIGIN[0]) * 364000 * Math.cos((ORIGIN[1] * Math.PI) / 180) * FT
+      const elevation = holeEvery > 0 && i % holeEvery === 3 ? null : base + slopeFtPerM * xM
+      return { lat: p.lat, lng: p.lng, elevation }
+    })
+    return { ok: true, results }
+  }
+}
+
+describe('grid and projection', () => {
+  test('the grid pads the lot bbox and runs row-major; the projection inverts the plan frame', () => {
+    const g = gridOver(LOT, 5)
+    expect(g.n).toBe(5)
+    expect(g.points).toHaveLength(25)
+    expect(g.x0).toBeCloseTo(-15.24 * 0.08, 6)
+    expect(g.x1).toBeCloseTo(15.24 * 1.08, 6)
+    expect(g.points[0]).toEqual([g.x0, g.z0])
+    expect(g.points[4]![0]).toBeCloseTo(g.x1, 9)
+    expect(g.points[5]![1]).toBeCloseTo(g.z0 + (g.z1 - g.z0) / 4, 9)
+    const ll = localMetresToLngLat([100 * FT, 200 * FT], ORIGIN)
+    // 100 ft east, 200 ft south of the origin
+    expect(ll.lat).toBeCloseTo(ORIGIN[1] - 200 / 364000, 9)
+    expect(ll.lng).toBeCloseTo(
+      ORIGIN[0] + 100 / (364000 * Math.cos((ORIGIN[1] * Math.PI) / 180)),
+      9,
+    )
+  })
+
+  test('bilinear reads interpolate the coarse grid and fill holes', () => {
+    const g = gridOver(LOT, 3)
+    const elev = g.points.map((p) => p[0]) // elevation = x
+    expect(coarseHeightAt(g, elev, 7, 10, 0)).toBeCloseTo(7, 6)
+    const holed = elev.map((v, i) => (i === 4 ? null : v))
+    // the centre sample is a hole → the fill (the mean) stands in for it
+    const mean = elev.reduce((s, v) => s + v, 0) / elev.length
+    expect(coarseHeightAt(g, holed, (g.x0 + g.x1) / 2, (g.z0 + g.z1) / 2, mean)).toBeCloseTo(
+      mean,
+      6,
+    )
+  })
+
+  test('the heightfield follows the samples relative to the datum', () => {
+    const g = gridOver(LOT, 5)
+    const elevM = g.points.map((p) => 0.1 * p[0]) // 10 % grade in x, metres
+    const field = fieldFromSamples(g, elevM, 0.1 * 7.62, 0)
+    expect(heightAt(field, 7.62, 10)).toBeCloseTo(0, 2)
+    expect(heightAt(field, 0, 10)).toBeCloseTo(-0.762, 2)
+    expect(heightAt(field, 15, 5)).toBeCloseTo(0.738, 2)
+    expect(field.cols).toBeLessThanOrEqual(129)
+  })
+})
+
+describe('sampleLotTerrain', () => {
+  test('a sloping lot writes a heightfield with the datum at the lot centre and says how much fall', async () => {
+    const r = await sampleLotTerrain(LOT, ORIGIN, { provider: fakeProvider(0.3), now: () => 't' })
+    expect(r.ok).toBe(true)
+    expect(r.terrain).toBeDefined()
+    expect(r.summary?.flat).toBe(false)
+    expect(r.summary?.grid).toBe(DEFAULT_GRID_N)
+    expect(r.summary?.sampled).toBe(81)
+    // the datum is the ground at the lot centre (x = 7.62 m): 30 + 0.3 × 7.62 ft
+    expect(r.summary?.datumFt).toBeCloseTo(30 + 0.3 * 7.62, 4)
+    const field = decodeTerrainField(r.terrain)
+    expect(field).not.toBeNull()
+    // 0.3 ft per metre of x: 7.62 m west of the centre the ground is 2.29 ft lower
+    expect(heightAt(field!, 0, 16.3)).toBeCloseTo(-0.3 * 7.62 * FT, 2)
+    expect(heightAt(field!, 7.62, 16.3)).toBeCloseTo(0, 2)
+    expect(heightAt(field!, 15.24, 16.3)).toBeCloseTo(0.3 * 7.62 * FT, 2)
+  })
+
+  test('a flat lot writes nothing; holes are counted; failures say why', async () => {
+    const flat = await sampleLotTerrain(LOT, ORIGIN, { provider: fakeProvider(0.001) })
+    expect(flat.ok).toBe(true)
+    expect(flat.terrain).toBeUndefined()
+    expect(flat.summary?.flat).toBe(true)
+    expect(flat.summary!.reliefFt * FT).toBeLessThan(MIN_RELIEF_M)
+    const holed = await sampleLotTerrain(LOT, ORIGIN, { provider: fakeProvider(0.3, 30, 7) })
+    expect(holed.ok).toBe(true)
+    expect(holed.summary!.holes).toBeGreaterThan(0)
+    expect(holed.summary!.sampled + holed.summary!.holes).toBe(81)
+    const down = await sampleLotTerrain(LOT, ORIGIN, { provider: fakeProvider(0.3, 30, 0, true) })
+    expect(down.ok).toBe(false)
+    expect(down.reason).toBe('USGS down')
+    const thrown = await sampleLotTerrain(LOT, ORIGIN, {
+      provider: async () => {
+        throw new Error('offline')
+      },
+    })
+    expect(thrown.ok).toBe(false)
+    expect(thrown.reason).toBe('offline')
+    expect((await sampleLotTerrain([[0, 0]], ORIGIN)).reason).toBe('no lot ring')
+  })
+
+  test('the status fragment reads plainly', () => {
+    expect(describeTerrainSample(null, 'USGS down')).toBe(
+      'terrain read failed (USGS down) — the ground is flat until it is read',
+    )
+    expect(describeTerrainSample(null, 'skipped')).toBe('')
+    expect(
+      describeTerrainSample(
+        {
+          source: 'USGS EPQS',
+          grid: 9,
+          sampled: 79,
+          holes: 2,
+          datumFt: 30,
+          reliefFt: 4.56,
+          flat: false,
+          at: 't',
+        },
+        '',
+      ),
+    ).toBe("terrain: 4.6' of fall across the lot (USGS, 79 pts, 2 unread)")
+    expect(
+      describeTerrainSample(
+        {
+          source: 'USGS EPQS',
+          grid: 9,
+          sampled: 81,
+          holes: 0,
+          datumFt: 30,
+          reliefFt: 0.2,
+          flat: true,
+          at: 't',
+        },
+        '',
+      ),
+    ).toBe('ground flat within 2" (USGS)')
+  })
+})