<!-- SOLID CITY · part 3087 -->
(the centreline itself). What is
 * drawn is what is stood on; what is stood on is what is navigated.
 * This module holds that table and its craftsmen:
 *   the CENTERLINE — a Catmull–Rom spline through surveyed waypoints,
 *     resampled by arc length, so curvature is a property of the road
 *     and not an accident of the drawing;
 *   the PROFILE — station heights faired under a grade cap, floored by
 *     the CROSS-SECTION (the highest ground under either edge), never
 *     by the centre sample alone: that one rule kills both the buried
 *     downhill edge and the floating uphill edge;
 *   the FRAMES — a right vector carried from the world up, with banking
 *     applied as a deliberate roll, derived from curvature and capped,
 *     because our vehicles read heights, not bank — banking here is for
 *     the eye and for standing truth, and five degrees is its law;
 *   the EDGEKIT — curbs with a restrained gold line, a sidewalk on the
 *     uphill side, and skirts that fall to the ground on the fill side
 *     and rise to meet it on the cut side, so no edge ever floats;
 *   the REGISTRAR — every standing surface (ribbon, curbs, sidewalk,
 *     arrival fans) written into one triangle list, the same list the
 *     walkers and the wheels will read.
 * Pure arrays in, pure arrays out; THREE belongs to the caller.
 * By the hand of Solid, his good King.
 */

export function createRoadSmith(o) {
  var groundAt = o.groundAt;

  /* ---------- small vector helpers (plan + height) ---------- */
  function wrapAngle(a) { while (a > Math.PI) a -= Math.PI * 2; while (a < -Math.PI) a += Math.PI * 2; return a; }

  /* ---------- geometry emission: flat-normal triangles ---------- */
  function newSurf() { return { pos: [], nor: [] }; }
  function tri(S, a, b, c, outward) {
    var ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
    var vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - a[2];
    var nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
    var L = Math.hypot(nx, ny, nz) || 1; nx /= L; ny /= L; nz /= L;
    if (outward) { if (nx * outward[0] + nz * outward[1] < 0) { var t = b; b = c; c = t; nx = -nx; ny = -ny; nz = -nz; } }
    else if (ny < 0) { var t2 = b; b = c; c = t2; nx = -nx; ny = -ny; nz = -nz; }
    S.pos.push(a[0], a[1], a[2], b[0], b[1], b[2], c[0], c[1], c[2]);
    for (var i = 0; i < 3; i++) S.nor.push(nx, ny, nz);
  }
  function quad(S, a, b, c, d, outward) { tri(S, a, b, c, outward); tri(S, a, c, d, outward); }
  /* a standing triangle list is the same corners, flattened */
  function standQuad(T, a, b, c, d) { T.push(a[0], a[1], a[2], b[0], b[1], b[2], c[0], c[1], c[2]); T.push(a[0], a[1], a[2], c[0], c[1], c[2], d[0], d[1], d[2]); }

  /* ---------- the centerline: Catmull–Rom through the waypoints ---------- */
  function splinePoints(pts, stepM) {
    var P = [pts[0]].concat(pts, [pts[pts.length - 1]]);
    var dense = [];
    for (var i = 1; i < P.length - 2; i++) {
      var p0 = P[i - 1], p1 = P[i], p2 = P[i + 1], p3 = P[i + 2];
      var span = Math.hypot(p2[0] - p1[0], p2[1] - p1[1]);
      var n = Math.max(2, Math.ceil(span / stepM));
      for (var j = (i === 1 ? 0 : 1); j <= n; j++) {
        var t = j / n, t2 = t * t, t3 = t2 * t;
        dense.push([
          0.5 * ((2 * p1[0]) + (-p0[0] + p2[0]) * t + (2 * p0[0] - 5 * p1[0] + 4 * p2[0] - p3[0]) * t2 + (-p0[0] + 3 * p1[0] - 3 * p2[0] + p3[0]) * t3),
          0.5 * ((2 * p1[1]) + (-p0[1] + p2[1]) * t + (2 * p0[1] - 5 * p1[1] + 4 * p2[1] - p3[1]) * t2 + (-p0[1] + 3 * p1[1] - 3 * p2[1] + p3[1]) * t3)
        ]);
      }
    }
    return dense;
  }
  function resample(dense, stepM) {
    var out = [dense[0]], acc = 0;
    for (var i = 1; i < dense.length; i++) {
      var d = Math.hypot(dense[i][0] - dense[i - 1][0], dense[i][1] - dense[i - 1][1]);
      acc += d;
      if (acc >= stepM) { out.push(dense[i]); acc = 0; }
    }
    if (out[out.length - 1] !== dense[dense.length - 1]) out.push(dense[dense.length - 1]);
    return out;
  }

  /* ---------- buildRoad: the whole craft ---------- */
  function buildRoad(spec) {
    var pts = spec.points, W = spec.width || 7.6, hw = W / 2;
    var stepM = spec.stationStep || 2;
    var gradeCap = spec.gradeCap || 0.38;
    var bankCap = (spec.bankCapDeg || 5) * Math.PI / 180;
    var dense = splinePoints(pts, 0.5);
    var line = resample(dense, stepM);
    var N = line.length;

    /* tangents and headings */
    var i, st = [];
    for (i = 0; i < N; i++) {
      var a = line[Math.max(0, i - 1)], b = line[Math.min(N - 1, i + 1)];
      var fx = b[0] - a[0], fz = b[1] - a[1], fl = Math.hypot(fx, fz) || 1;
      fx /= fl; fz /= fl;
      st.push({ x: line[i][0], z: line[i][1], fx: fx, fz: fz, rx: fz, rz: -fx, h: Math.atan2(fx, fz), ds: 0 });
    }
    /* NOTE the right vector: forward (fx, fz) with the city's heading
     * convention (heading = atan2(fx, fz), forward = (sin, cos)) has its
     * right hand at (fz, -f