@pascal-app/core 1.0.4 → 1.0.6

package/dist/lib/setback-envelope.js

@@ -68,7 +68,7 @@ export function arcRuns(points, shortM = 4, turnDeg = 35) {
     let runs = 0;
     // start the sweep at a long edge when there is one, so a run never wraps across the sweep's seam
     const start = dirs.findIndex((d) => d.len >= shortM);
-    const order = Array.from({ length: n }, (_, k) => ((start < 0 ? 0 : start) + k) % n);
+    const order = Array.from({ length: n }, (_, k) => (Math.max(start, 0) + k) % n);
     for (const i of order) {
         if (run[i] !== -1)
             continue;
@@ -369,61 +369,41 @@ export function insetPolygon(points, distances, options = {}) {
 }
 /**
  * Which envelope edge is the one behind the lot's front line: the longest
- * envelope edge running parallel to it (within 25°) with its midpoint
- * nearest that line; failing that, the envelope edge whose midpoint is
- * nearest the lot front's midpoint (a pie lot's curved frontage has no
- * single parallel — its longest arc chord fronts the house).
+ * envelope edge facing the same way (within 25°) with its midpoint nearest
+ * that line. Facing, not only parallel: on a lot that widens away from its
+ * street the rear edge is parallel too, and longer. Null when no edge faces
+ * the street: side setbacks wider than a narrow frontage take the whole
+ * front, and a side is no front.
  */
 export function envelopeFrontEdge(lot, frontIndex, envelope) {
     const n = lot.length;
     const m = envelope.length;
     if (n < 2 || m < 2)
-        return 0;
+        return null;
     const fi = ((frontIndex % n) + n) % n;
     const a = lot[fi];
     const b = lot[(fi + 1) % n];
-    const fx = b[0] - a[0];
-    const fy = b[1] - a[1];
-    const fl = Math.hypot(fx, fy) || 1;
-    const ux = fx / fl;
-    const uy = fy / fl;
-    const fmid = [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
-    let bestI = -1;
+    const [fnx, fny] = outwardNormal(lot, fi);
+    let best = null;
     let bestScore = Number.NEGATIVE_INFINITY;
     for (let i = 0; i < m; i++) {
         const p = envelope[i];
         const q = envelope[(i + 1) % m];
-        const ex = q[0] - p[0];
-        const ey = q[1] - p[1];
-        const el = Math.hypot(ex, ey);
+        const el = Math.hypot(q[0] - p[0], q[1] - p[1]);
         if (el < 1e-6)
             continue;
-        const par = Math.abs((ex * ux + ey * uy) / el);
-        if (par < Math.cos((25 * Math.PI) / 180))
+        const [enx, eny] = outwardNormal(envelope, i);
+        if (enx * fnx + eny * fny < Math.cos((25 * Math.PI) / 180))
             continue;
-        const mid = [(p[0] + q[0]) / 2, (p[1] + q[1]) / 2];
-        const dist = segDist(mid[0], mid[1], a, b);
+        const dist = segDist((p[0] + q[0]) / 2, (p[1] + q[1]) / 2, a, b);
         // long and close wins: the front's offset is one lot-front length away by the setback
         const score = el - 2 * dist;
         if (score > bestScore) {
             bestScore = score;
-            bestI = i;
+            best = i;
         }
     }
-    if (bestI >= 0)
-        return bestI;
-    let nearest = 0;
-    let nd = Number.POSITIVE_INFINITY;
-    for (let i = 0; i < m; i++) {
-        const p = envelope[i];
-        const q = envelope[(i + 1) % m];
-        const d = Math.hypot((p[0] + q[0]) / 2 - fmid[0], (p[1] + q[1]) / 2 - fmid[1]);
-        if (d < nd) {
-            nd = d;
-            nearest = i;
-        }
-    }
-    return nearest;
+    return best;
 }
 /**
  * The CORNER SIGHT TRIANGLE at a street intersection (the clear-vision /
@@ -504,3 +484,339 @@ export function streetCorners(points, streetEdges) {
     }
     return out;
 }
+/** Unit normal of edge `i` pointing OUT of the polygon, winding-agnostic. */
+export function outwardNormal(points, i) {
+    const n = points.length;
+    const p = points[i % n];
+    const q = points[(i + 1) % n];
+    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 = signedArea(points) > 0 ? -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, i, northRotation = 0) {
+    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;
+}
+/** Length of edge `i`, metres. */
+export function edgeLength(points, i) {
+    const n = points.length;
+    const p = points[i % n];
+    const q = points[(i + 1) % n];
+    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, northRotation = 0) {
+    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, frontEdge, northRotation = 0) {
+    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, frontIndex, streetEdges = []) {
+    const n = points.length;
+    const roles = 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];
+    const fq = points[(front + 1) % n];
+    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];
+        const q = points[(i + 1) % n];
+        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, role) {
+    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
+ * (`insetPolygon`): straight where the lot is straight, concentric round a
+ * radius, clipped where the offsets cross. 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.
+ *
+ * Returns `[]` when the polygon has fewer than 3 points, when a setback is
+ * not a distance, or when nothing buildable remains (setbacks larger than
+ * the lot).
+ */
+export function setbackEnvelope(points, setbacks, frontIndex, options = {}) {
+    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();
+    const streetLike = (r) => r === 'front' || r === 'street';
+    for (let i = 0; i < n; i++) {
+        const r = roles[i];
+        const g = runs[i];
+        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];
+        const have = runRole.get(g);
+        if (streetLike(have))
+            continue;
+        const before = roles[(i - 1 + n) % n];
+        const after = roles[(i + 1) % n];
+        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) => runRole.get(runs[(i + n) % n]) ?? roles[(i + n) % n];
+    const direction = (i) => {
+        const p = points[(i + n) % n];
+        const q = points[(i + 1 + n) % n];
+        const l = Math.hypot(q[0] - p[0], q[1] - p[1]) || 1;
+        return [(q[0] - p[0]) / l, (q[1] - p[1]) / l];
+    };
+    const straightOn = Math.cos((8 * Math.PI) / 180);
+    const continued = new Map();
+    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 = [];
+    for (let i = 0; i < n; i++) {
+        const role = continued.get(i) ?? runRole.get(runs[i]) ?? roles[i];
+        const d = setbackForRole(setbacks, role === 'left' || role === 'right' ? roles[i] : 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 = [];
+    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 });
+        }
+    }
+    return insetPolygon(points, distances, { keepOut });
+}
+/* ------------------------------------------------------------- yards */
+/**
+ * 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, origin, dx, dy) {
+    const n = points.length;
+    let best = null;
+    for (let i = 0; i < n; i++) {
+        const p = points[i];
+        const q = points[(i + 1) % n];
+        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;
+}
+/**
+ * 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 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. Sides whose ray misses the lot
+ * line (footprint outside the lot) are omitted rather than faked.
+ */
+export function castYardDimensionsOriented(lot, footprintLoops, yaw) {
+    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) => [c * p[0] - s * p[1], s * p[0] + c * p[1]];
+    const toWorld = (p) => [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: [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 = ['north', 'east', 'south', 'west'];
+    const out = [];
+    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];
+        out.push({ side, from, to: hit.point, distance: hit.distance });
+    }
+    return out;
+}

package/dist/lib/site-flatwork.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a node is flatwork the site's works laid on a level (`add_site_surface`: a lawn, a
+ * driveway, a path, a patio, marked `metadata.flatwork`). It stands on the building's level for its
+ * elevation, but it is outdoors and not a floor of the building: it takes no part in where the
+ * building stands against the ground (a lot-wide lawn under a hill is not a floor buried by it), in
+ * what covers a basement (a lawn does not), or in the box the level's rooms stand in.
+ */
+export declare function isSiteFlatwork(node: {
+    metadata?: unknown;
+}): boolean;
+//# sourceMappingURL=site-flatwork.d.ts.map

package/dist/lib/site-flatwork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-flatwork.d.ts","sourceRoot":"","sources":["../../src/lib/site-flatwork.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAGpE"}

package/dist/lib/site-flatwork.js

@@ -0,0 +1,11 @@
+/**
+ * Whether a node is flatwork the site's works laid on a level (`add_site_surface`: a lawn, a
+ * driveway, a path, a patio, marked `metadata.flatwork`). It stands on the building's level for its
+ * elevation, but it is outdoors and not a floor of the building: it takes no part in where the
+ * building stands against the ground (a lot-wide lawn under a hill is not a floor buried by it), in
+ * what covers a basement (a lawn does not), or in the box the level's rooms stand in.
+ */
+export function isSiteFlatwork(node) {
+    const metadata = node.metadata;
+    return typeof metadata === 'object' && metadata !== null && 'flatwork' in metadata;
+}

package/dist/lib/site-ground-height.d.ts

@@ -0,0 +1,13 @@
+import type { AnyNode } from '../schema/index.js';
+/**
+ * Where a flat site's ground lies: the plane the site renderer draws its fill on, a hand under
+ * the datum so the floors laid at grade sit on it and never inside it.
+ */
+export declare const FLAT_GROUND_Y = -0.05;
+/**
+ * The height of the site's ground at a world XZ, as the renderer draws it: the sculpted terrain
+ * where the site has one, the flat plane everywhere else. `site` is the site node (the caller
+ * knows it; looking it up here would walk every node for every call).
+ */
+export declare function groundHeightAt(site: AnyNode | null | undefined, x: number, z: number): number;
+//# sourceMappingURL=site-ground-height.d.ts.map

package/dist/lib/site-ground-height.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-ground-height.d.ts","sourceRoot":"","sources":["../../src/lib/site-ground-height.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAIxC;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAQ,CAAA;AAElC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7F"}

package/dist/lib/site-ground-height.js

@@ -0,0 +1,16 @@
+import { heightAt } from './terrain-field.js';
+import { terrainFieldOf } from './terrain-source.js';
+/**
+ * Where a flat site's ground lies: the plane the site renderer draws its fill on, a hand under
+ * the datum so the floors laid at grade sit on it and never inside it.
+ */
+export const FLAT_GROUND_Y = -0.05;
+/**
+ * The height of the site's ground at a world XZ, as the renderer draws it: the sculpted terrain
+ * where the site has one, the flat plane everywhere else. `site` is the site node (the caller
+ * knows it; looking it up here would walk every node for every call).
+ */
+export function groundHeightAt(site, x, z) {
+    const field = site?.type === 'site' ? terrainFieldOf(site) : null;
+    return field ? heightAt(field, x, z) : FLAT_GROUND_Y;
+}