@pascal-app/nodes 1.0.4 → 1.0.5

package/dist/site/ground-hole.d.ts

@@ -0,0 +1,92 @@
+import { type UndergroundEdge } from '@pascal-app/viewer';
+/**
+ * The ground as the medium, seen from above: over a level below grade the ground stays solid and
+ * a hole opens in it over the below-grade footprint, through which the level is seen clearly. The
+ * hole's edge is a noise threshold, an eroded border: the distance from the footprint is compared
+ * to a radius that wanders with a fractal perlin noise (broad waves with finer ones riding them),
+ * so the cut is a living, eroded line rather than an offset outline. Along it the ground darkens
+ * in a soft feather and a thin light line marks the cut itself.
+ *
+ * The footprint is a signed-distance field baked on the CPU into a small texture when the
+ * footprints change (the polygons the grade ring is drawn from), so the ground's mask costs one
+ * texture fetch and one noise lookup per fragment, whatever the building's outline. How far the
+ * hole is open (0 to 1, eased, 0 in a capture) is the viewer's `groundHoleOpenNode`.
+ */
+/**
+ * The shipped edge's base margin around the footprint (metres) and how far the noise moves the
+ * edge in or out of it. The edge looks (`underground-edge.ts`) vary both, and the noise's scale
+ * (cells per metre of its broadest octave, ~1.7 m waves at today's), through uniforms.
+ */
+export declare const HOLE_MARGIN: number;
+export declare const HOLE_ERODE: number;
+/**
+ * Sets the hole's edge look: the shader's margin, erosion, noise scale, feather and line (all
+ * uniforms, nothing recompiles), and the CPU's twin of them. The pit's walls are cut again by
+ * `GroundHole` after this.
+ */
+export declare function setGroundHoleEdge(edge: UndergroundEdge): void;
+type Point = readonly [number, number];
+/**
+ * Bakes the signed distance to `polygons` (the below-grade footprints, world plan) into the
+ * hole's texture. No polygons: the field is far everywhere, so the ground has no hole.
+ */
+export declare function setGroundHoleFootprints(polygons: ReadonlyArray<ReadonlyArray<Point>>): void;
+/** The baked signed distance to the footprints at a world XZ (bilinear, as the shader reads it). */
+export declare function groundHoleDistanceAt(x: number, z: number): number;
+/** The baked field's box in the world's plan, `null` while no footprint is baked. */
+export declare function groundHoleBox(): {
+    originX: number;
+    originZ: number;
+    span: number;
+} | null;
+/**
+ * The hole's radius at a world XZ at full opening, as the shader's noise gives it: what the pit's
+ * walls are laid along (`hole-noise.ts` is that noise on the CPU).
+ */
+export declare function holeRadiusAt(x: number, z: number): number;
+/**
+ * The CPU twin of the hole for one pick: whether `(x, z)` is surely in the hole now. The edge's
+ * noise is not replayed here, so this is the part of the hole that is open whatever the noise
+ * does (margin less the full erosion): a click there falls through to the floor under it, and a
+ * click in the wandering fringe still lands on the ground.
+ */
+export declare function groundHoleContains(x: number, z: number): boolean;
+/**
+ * The mask the solid ground draws with: the ground window's, and not in the hole (the hole's
+ * edge being the noise threshold). Everywhere with the window and the hole closed.
+ */
+export declare function solidGroundMaskNode(): import("three/webgpu").Node<"bool">;
+/** Whether a fragment is in the hole, a hand's width over: what the pit's floor is drawn in. */
+export declare function groundHoleFloorNode(): any;
+/**
+ * How the solid ground receives shadows while the hole is open: not at all. The storeys that are
+ * hidden above the level shown still cast their shadows (so the rooms stay shaded), and on the
+ * ground that would read as ghosts of a building that is not there.
+ */
+export declare function groundHoleShadowNode(): () => any;
+/**
+ * The ground's colour with a soft shade (`shadeColor`) feathered along the hole's cut and a thin
+ * light line on the cut itself; the plain colour with the hole closed.
+ */
+export declare function groundHoleColorNode(shadeColor: string): import("three/webgpu").Node<"vec3">;
+/**
+ * Feeds the hole the footprints it is cut over (the polygons the grade ring runs along: the level
+ * shown and the ones between it and grade), and says to the rest of the viewer whether the scene
+ * has a level below grade at all (`present`): the ground materials carry the hole's mask, and the
+ * eye's fill light is mounted, from then on, once, so that changing floors only changes uniforms.
+ *
+ * It also stands the pit in the hole (`ground-pit.tsx`): walls cut along the hole's own contour
+ * from the ground (`topAt`, at `topY` flat) down to `floorY`, the floor of the level shown, in the
+ * `topsoil` colour at their top; its dark floor is drawn at `drawnFloorY` (`groundPitFloorY`).
+ */
+export declare function GroundHole({ footprints, present, floorY, drawnFloorY, topY, topAt, topsoil, }: {
+    footprints: ReadonlyArray<ReadonlyArray<Point>>;
+    present: boolean;
+    floorY: number | null;
+    drawnFloorY: number | null;
+    topY: number;
+    topAt: (x: number, z: number) => number;
+    topsoil: string;
+}): import("react").JSX.Element | null;
+export {};
+//# sourceMappingURL=ground-hole.d.ts.map

package/dist/site/ground-hole.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-hole.d.ts","sourceRoot":"","sources":["../../src/site/ground-hole.tsx"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,eAAe,EAErB,MAAM,oBAAoB,CAAA;AA4B3B;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,QAA0B,CAAA;AAClD,eAAO,MAAM,UAAU,QAAyB,CAAA;AA8BhD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAU7D;AAED,KAAK,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAuCtC;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAsD3F;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAcjE;AAED,qFAAqF;AACrF,wBAAgB,aAAa,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAEzF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzD;AAKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAIhE;AAkCD;;;GAGG;AACH,wBAAgB,mBAAmB,wCAElC;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,QAElC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,CAIhD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,uCAIrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EACzB,UAAU,EACV,OAAO,EACP,MAAM,EACN,WAAW,EACX,IAAI,EACJ,KAAK,EACL,OAAO,GACR,EAAE;IACD,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;CAChB,sCAgDA"}

package/dist/site/ground-hole.js

@@ -0,0 +1,306 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { groundHoleOpenNode, groundHoleOpenNow, groundWindowMaskNode, useViewer, } from '@pascal-app/viewer';
+import { useEffect, useState } from 'react';
+import { ClampToEdgeWrapping, Color, DataTexture, LinearFilter, RedFormat, UnsignedByteType, } from 'three';
+import { color, float, materialColor, mix, mx_fractal_noise_float, positionWorld, smoothstep, texture, uniform, vec3, } from 'three/tsl';
+import { Vector2 } from 'three/webgpu';
+import { GroundPit, setGroundPitEdge } from './ground-pit.js';
+import { buildPitWalls } from './ground-pit-geometry.js';
+import { fractalNoise3 } from './hole-noise.js';
+import { EDGE_LOOKS } from './underground-edge.js';
+/**
+ * The ground as the medium, seen from above: over a level below grade the ground stays solid and
+ * a hole opens in it over the below-grade footprint, through which the level is seen clearly. The
+ * hole's edge is a noise threshold, an eroded border: the distance from the footprint is compared
+ * to a radius that wanders with a fractal perlin noise (broad waves with finer ones riding them),
+ * so the cut is a living, eroded line rather than an offset outline. Along it the ground darkens
+ * in a soft feather and a thin light line marks the cut itself.
+ *
+ * The footprint is a signed-distance field baked on the CPU into a small texture when the
+ * footprints change (the polygons the grade ring is drawn from), so the ground's mask costs one
+ * texture fetch and one noise lookup per fragment, whatever the building's outline. How far the
+ * hole is open (0 to 1, eased, 0 in a capture) is the viewer's `groundHoleOpenNode`.
+ */
+/**
+ * The shipped edge's base margin around the footprint (metres) and how far the noise moves the
+ * edge in or out of it. The edge looks (`underground-edge.ts`) vary both, and the noise's scale
+ * (cells per metre of its broadest octave, ~1.7 m waves at today's), through uniforms.
+ */
+export const HOLE_MARGIN = EDGE_LOOKS.noise.margin;
+export const HOLE_ERODE = EDGE_LOOKS.noise.erode;
+/**
+ * Three octaves, each finer and weaker than the last (cell size 1.7 m, 0.8 m, 0.4 m). The sum is
+ * divided by its largest value, so the noise stays within ±1 and the hole's guaranteed core
+ * (margin less the full erosion) still holds; the fine octaves are weak enough that the edge
+ * never folds over into islets.
+ */
+const NOISE_LACUNARITY = 2.1;
+const NOISE_DIMINISH = 0.4;
+const NOISE_NORMALISE = 1 / (1 + NOISE_DIMINISH + NOISE_DIMINISH ** 2);
+/** How far the pit's floor reaches past the hole's cut, in metres (under the walls). */
+const FLOOR_OVERLAP = 0.08;
+const GRID = 192;
+/** The signed distance the texture stores: metres, negative inside, clamped to this range. */
+const RANGE_MIN = -6;
+const RANGE_MAX = 10;
+/** Texture margin past the footprint's box: where the hole can reach, and some. */
+const PAD = HOLE_MARGIN + HOLE_ERODE + 3;
+let look = EDGE_LOOKS.noise;
+const holeMargin = uniform(look.margin);
+const holeErode = uniform(look.erode);
+const holeScale = uniform(look.scale);
+const featherWidth = uniform(look.featherWidth);
+const featherStrength = uniform(look.featherStrength);
+const lineWidth = uniform(look.lineWidth);
+const lineColor = uniform(new Color(look.lineColor));
+/**
+ * Sets the hole's edge look: the shader's margin, erosion, noise scale, feather and line (all
+ * uniforms, nothing recompiles), and the CPU's twin of them. The pit's walls are cut again by
+ * `GroundHole` after this.
+ */
+export function setGroundHoleEdge(edge) {
+    look = EDGE_LOOKS[edge];
+    holeMargin.value = look.margin;
+    holeErode.value = look.erode;
+    holeScale.value = look.scale;
+    featherWidth.value = look.featherWidth;
+    featherStrength.value = look.featherStrength;
+    lineWidth.value = look.lineWidth;
+    lineColor.value.set(look.lineColor);
+    setGroundPitEdge(look);
+}
+const field = new Uint8Array(GRID * GRID).fill(255);
+const fieldTexture = new DataTexture(field, GRID, GRID, RedFormat, UnsignedByteType);
+fieldTexture.minFilter = LinearFilter;
+fieldTexture.magFilter = LinearFilter;
+fieldTexture.wrapS = ClampToEdgeWrapping;
+fieldTexture.wrapT = ClampToEdgeWrapping;
+fieldTexture.generateMipmaps = false;
+fieldTexture.needsUpdate = true;
+const gridOrigin = uniform(new Vector2(0, 0));
+const gridSpan = uniform(1);
+let originX = 0;
+let originZ = 0;
+let span = 1;
+let hasField = false;
+function encode(distance) {
+    const t = (distance - RANGE_MIN) / (RANGE_MAX - RANGE_MIN);
+    return Math.round(Math.min(1, Math.max(0, t)) * 255);
+}
+function decode(value) {
+    return RANGE_MIN + (value / 255) * (RANGE_MAX - RANGE_MIN);
+}
+function insidePolygons(polygons, x, z) {
+    let inside = false;
+    for (const polygon of polygons) {
+        for (let a = 0, b = polygon.length - 1; a < polygon.length; b = a, a += 1) {
+            const [ax, az] = polygon[a];
+            const [bx, bz] = polygon[b];
+            if (az > z !== bz > z && x < ((bx - ax) * (z - az)) / (bz - az) + ax)
+                inside = !inside;
+        }
+    }
+    return inside;
+}
+/**
+ * Bakes the signed distance to `polygons` (the below-grade footprints, world plan) into the
+ * hole's texture. No polygons: the field is far everywhere, so the ground has no hole.
+ */
+export function setGroundHoleFootprints(polygons) {
+    const points = polygons.flat();
+    if (points.length === 0) {
+        if (hasField) {
+            field.fill(255);
+            fieldTexture.needsUpdate = true;
+            hasField = false;
+        }
+        return;
+    }
+    let minX = Number.POSITIVE_INFINITY;
+    let minZ = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxZ = Number.NEGATIVE_INFINITY;
+    for (const [x, z] of points) {
+        minX = Math.min(minX, x);
+        maxX = Math.max(maxX, x);
+        minZ = Math.min(minZ, z);
+        maxZ = Math.max(maxZ, z);
+    }
+    span = Math.max(maxX - minX, maxZ - minZ) + 2 * PAD;
+    originX = (minX + maxX) / 2 - span / 2;
+    originZ = (minZ + maxZ) / 2 - span / 2;
+    gridOrigin.value.set(originX, originZ);
+    gridSpan.value = span;
+    const edges = [];
+    for (const polygon of polygons)
+        for (let a = 0, b = polygon.length - 1; a < polygon.length; b = a, a += 1)
+            edges.push(polygon[b][0], polygon[b][1], polygon[a][0], polygon[a][1]);
+    const cell = span / GRID;
+    for (let row = 0; row < GRID; row += 1) {
+        const z = originZ + (row + 0.5) * cell;
+        for (let col = 0; col < GRID; col += 1) {
+            const x = originX + (col + 0.5) * cell;
+            let best = Number.POSITIVE_INFINITY;
+            for (let i = 0; i < edges.length; i += 4) {
+                const ax = edges[i];
+                const az = edges[i + 1];
+                const dx = edges[i + 2] - ax;
+                const dz = edges[i + 3] - az;
+                const length2 = dx * dx + dz * dz;
+                let t = length2 > 0 ? ((x - ax) * dx + (z - az) * dz) / length2 : 0;
+                t = Math.min(1, Math.max(0, t));
+                const ex = x - (ax + dx * t);
+                const ez = z - (az + dz * t);
+                const d2 = ex * ex + ez * ez;
+                if (d2 < best)
+                    best = d2;
+            }
+            const distance = Math.sqrt(best);
+            field[row * GRID + col] = encode(insidePolygons(polygons, x, z) ? -distance : distance);
+        }
+    }
+    fieldTexture.needsUpdate = true;
+    hasField = true;
+}
+/** The baked signed distance to the footprints at a world XZ (bilinear, as the shader reads it). */
+export function groundHoleDistanceAt(x, z) {
+    if (!hasField)
+        return RANGE_MAX;
+    const u = Math.min(GRID - 1, Math.max(0, ((x - originX) / span) * GRID - 0.5));
+    const v = Math.min(GRID - 1, Math.max(0, ((z - originZ) / span) * GRID - 0.5));
+    const c0 = Math.floor(u);
+    const r0 = Math.floor(v);
+    const c1 = Math.min(GRID - 1, c0 + 1);
+    const r1 = Math.min(GRID - 1, r0 + 1);
+    const tu = u - c0;
+    const tv = v - r0;
+    const at = (r, c) => decode(field[r * GRID + c]);
+    const top = at(r0, c0) * (1 - tu) + at(r0, c1) * tu;
+    const bottom = at(r1, c0) * (1 - tu) + at(r1, c1) * tu;
+    return top * (1 - tv) + bottom * tv;
+}
+/** The baked field's box in the world's plan, `null` while no footprint is baked. */
+export function groundHoleBox() {
+    return hasField ? { originX, originZ, span } : null;
+}
+/**
+ * The hole's radius at a world XZ at full opening, as the shader's noise gives it: what the pit's
+ * walls are laid along (`hole-noise.ts` is that noise on the CPU).
+ */
+export function holeRadiusAt(x, z) {
+    if (look.erode === 0)
+        return look.margin;
+    return (look.margin +
+        look.erode *
+            fractalNoise3(x * look.scale, z * look.scale, 0.31, 3, NOISE_LACUNARITY, NOISE_DIMINISH));
+}
+/** The fractal's own bound (three octaves of perlin within ±1): the radius stays within this of its margin. */
+const NOISE_BOUND = 1 + NOISE_DIMINISH + NOISE_DIMINISH ** 2;
+/**
+ * The CPU twin of the hole for one pick: whether `(x, z)` is surely in the hole now. The edge's
+ * noise is not replayed here, so this is the part of the hole that is open whatever the noise
+ * does (margin less the full erosion): a click there falls through to the floor under it, and a
+ * click in the wandering fringe still lands on the ground.
+ */
+export function groundHoleContains(x, z) {
+    const open = groundHoleOpenNow();
+    if (open <= 0.001)
+        return false;
+    return groundHoleDistanceAt(x, z) < (look.margin - look.erode) * open - 0.05;
+}
+// ── The shader pieces ────────────────────────────────────────────────────────────────────────
+let pieces = null;
+function holePieces() {
+    if (pieces)
+        return pieces;
+    const open = groundHoleOpenNode();
+    const uv = positionWorld.xz.sub(gridOrigin).div(gridSpan);
+    const distance = texture(fieldTexture, uv)
+        .r.mul(RANGE_MAX - RANGE_MIN)
+        .add(RANGE_MIN);
+    // One fractal lookup: the radius of the hole wanders around its margin.
+    const noise = mx_fractal_noise_float(vec3(positionWorld.xz.mul(holeScale), 0.31), 3, NOISE_LACUNARITY, NOISE_DIMINISH, NOISE_NORMALISE);
+    const radius = noise.mul(holeErode).add(holeMargin).mul(open);
+    const inHole = distance.lessThan(radius).and(open.greaterThan(0.001));
+    const opening = smoothstep(float(0), float(0.1), open);
+    const beyond = (width) => float(1)
+        .sub(smoothstep(radius, radius.add(width), distance))
+        .mul(opening);
+    // The pit's floor reaches a little past the cut, under the walls, so no hairline shows between.
+    const floorInHole = distance.lessThan(radius.add(FLOOR_OVERLAP)).and(open.greaterThan(0.001));
+    pieces = { inHole, floorInHole, feather: beyond(featherWidth), line: beyond(lineWidth) };
+    return pieces;
+}
+/**
+ * The mask the solid ground draws with: the ground window's, and not in the hole (the hole's
+ * edge being the noise threshold). Everywhere with the window and the hole closed.
+ */
+export function solidGroundMaskNode() {
+    return groundWindowMaskNode().and(holePieces().inHole.not());
+}
+/** Whether a fragment is in the hole, a hand's width over: what the pit's floor is drawn in. */
+export function groundHoleFloorNode() {
+    return holePieces().floorInHole;
+}
+/**
+ * How the solid ground receives shadows while the hole is open: not at all. The storeys that are
+ * hidden above the level shown still cast their shadows (so the rooms stay shaded), and on the
+ * ground that would read as ghosts of a building that is not there.
+ */
+export function groundHoleShadowNode() {
+    const open = smoothstep(float(0), float(0.1), groundHoleOpenNode());
+    // three calls it with the shadow node (the typing says no argument).
+    return ((shadow) => mix(shadow, float(1), open));
+}
+/**
+ * The ground's colour with a soft shade (`shadeColor`) feathered along the hole's cut and a thin
+ * light line on the cut itself; the plain colour with the hole closed.
+ */
+export function groundHoleColorNode(shadeColor) {
+    const { feather, line } = holePieces();
+    const shaded = mix(materialColor, color(shadeColor), feather.mul(featherStrength));
+    return mix(shaded, lineColor, line);
+}
+/**
+ * Feeds the hole the footprints it is cut over (the polygons the grade ring runs along: the level
+ * shown and the ones between it and grade), and says to the rest of the viewer whether the scene
+ * has a level below grade at all (`present`): the ground materials carry the hole's mask, and the
+ * eye's fill light is mounted, from then on, once, so that changing floors only changes uniforms.
+ *
+ * It also stands the pit in the hole (`ground-pit.tsx`): walls cut along the hole's own contour
+ * from the ground (`topAt`, at `topY` flat) down to `floorY`, the floor of the level shown, in the
+ * `topsoil` colour at their top; its dark floor is drawn at `drawnFloorY` (`groundPitFloorY`).
+ */
+export function GroundHole({ footprints, present, floorY, drawnFloorY, topY, topAt, topsoil, }) {
+    const edge = useViewer((state) => state.undergroundLook.edge);
+    const [pit, setPit] = useState(null);
+    useEffect(() => {
+        setGroundHoleEdge(edge);
+        setGroundHoleFootprints(footprints);
+        const box = groundHoleBox();
+        setPit(box
+            ? {
+                walls: buildPitWalls({
+                    ...box,
+                    distanceAt: groundHoleDistanceAt,
+                    radiusAt: holeRadiusAt,
+                    topAt,
+                    radiusMin: look.margin - look.erode * NOISE_BOUND,
+                    radiusMax: look.margin + look.erode * NOISE_BOUND,
+                }),
+                box,
+            }
+            : null);
+    }, [footprints, topAt, edge]);
+    useEffect(() => {
+        if (useViewer.getState().hasLevelBelowGrade !== present)
+            useViewer.setState({ hasLevelBelowGrade: present });
+    }, [present]);
+    useEffect(() => () => {
+        setGroundHoleFootprints([]);
+        if (useViewer.getState().hasLevelBelowGrade)
+            useViewer.setState({ hasLevelBelowGrade: false });
+    }, []);
+    return present ? (_jsx(GroundPit, { box: pit?.box ?? null, drawnFloorY: drawnFloorY, floorY: floorY, inHole: groundHoleFloorNode(), topsoil: topsoil, topY: topY, walls: pit?.walls ?? null })) : null;
+}

package/dist/site/ground-pit-geometry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The pit's walls: the ground's hole cut open. The hole's edge is a threshold (the signed distance
+ * to the footprints against a radius that wanders with noise); this walks that same threshold on
+ * a fine grid (marching squares) and stands a wall of unit height (in `PIT_WALL_ROWS` rows) on every piece of the contour,
+ * facing into the hole. The wall's lower edge is not stored: each vertex carries a `drop` (0 at
+ * the ground, 1 at the bottom) the shader scales by the pit's current depth, so a floor switch
+ * moves a uniform and never rebuilds the walls.
+ */
+export type PitContourSource = {
+    /** The grid box to walk: world XZ of its corner and its side. */
+    originX: number;
+    originZ: number;
+    span: number;
+    /** Signed distance to the footprints, as the ground's mask reads it. */
+    distanceAt: (x: number, z: number) => number;
+    /** The wandering radius of the hole's edge at full opening. */
+    radiusAt: (x: number, z: number) => number;
+    /** Where the wall's top sits: the ground surface there. */
+    topAt: (x: number, z: number) => number;
+    /** The radius's smallest and largest value anywhere: far from both, the contour cannot be. */
+    radiusMin: number;
+    radiusMax: number;
+    /** Grid cell in metres (default 0.12). */
+    cell?: number;
+};
+export type PitWalls = {
+    positions: Float32Array;
+    normals: Float32Array;
+    /** x: 0 at the top of the wall, 1 at its foot. */
+    drops: Float32Array;
+    indices: Uint32Array;
+};
+/**
+ * Rows a wall is cut into down its drop, so the shader can push them sideways by depth: a wall of
+ * one row would stay a straight vertical fold from grade to the floor.
+ */
+export declare const PIT_WALL_ROWS = 16;
+export declare function buildPitWalls(source: PitContourSource): PitWalls | null;
+//# sourceMappingURL=ground-pit-geometry.d.ts.map

package/dist/site/ground-pit-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ground-pit-geometry.d.ts","sourceRoot":"","sources":["../../src/site/ground-pit-geometry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC5C,+DAA+D;IAC/D,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1C,2DAA2D;IAC3D,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAAA;IACvC,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,SAAS,EAAE,YAAY,CAAA;IACvB,OAAO,EAAE,YAAY,CAAA;IACrB,kDAAkD;IAClD,KAAK,EAAE,YAAY,CAAA;IACnB,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAuBD;;;GAGG;AACH,eAAO,MAAM,aAAa,KAAK,CAAA;AAM/B,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,GAAG,IAAI,CA6KvE"}

package/dist/site/ground-pit-geometry.js

@@ -0,0 +1,213 @@
+/**
+ * The pit's walls: the ground's hole cut open. The hole's edge is a threshold (the signed distance
+ * to the footprints against a radius that wanders with noise); this walks that same threshold on
+ * a fine grid (marching squares) and stands a wall of unit height (in `PIT_WALL_ROWS` rows) on every piece of the contour,
+ * facing into the hole. The wall's lower edge is not stored: each vertex carries a `drop` (0 at
+ * the ground, 1 at the bottom) the shader scales by the pit's current depth, so a floor switch
+ * moves a uniform and never rebuilds the walls.
+ */
+/** Segments joining the crossing points on cell edges 0 bottom, 1 right, 2 top, 3 left. */
+const CASES = [
+    [],
+    [[3, 0]],
+    [[0, 1]],
+    [[3, 1]],
+    [[1, 2]],
+    [], // 5: saddle, by the cell's centre
+    [[0, 2]],
+    [[3, 2]],
+    [[2, 3]],
+    [[0, 2]],
+    [], // 10: saddle
+    [[2, 1]],
+    [[3, 1]],
+    [[0, 1]],
+    [[3, 0]],
+    [],
+];
+const MAX_SEGMENTS = 120_000;
+/**
+ * Rows a wall is cut into down its drop, so the shader can push them sideways by depth: a wall of
+ * one row would stay a straight vertical fold from grade to the floor.
+ */
+export const PIT_WALL_ROWS = 16;
+/** How far past the radius's range a corner is taken as surely in (or out) without the noise, in metres. */
+const PRUNE = 0.5;
+/** Cells per side of the blocks the walk skips when they are far from the contour. */
+const BLOCK = 8;
+export function buildPitWalls(source) {
+    const { originX, originZ, span, distanceAt, radiusAt, topAt, radiusMin, radiusMax } = source;
+    const cell = source.cell ?? Math.max(0.12, span / 800);
+    const n = Math.ceil(span / cell);
+    const stride = n + 1;
+    // Far from the radius's whole range the contour cannot be: those corners are not looked up.
+    const inside = new Float32Array(stride * stride);
+    const field = (col, row) => {
+        const index = row * stride + col;
+        const known = inside[index];
+        if (known !== 0)
+            return known;
+        const x = originX + col * cell;
+        const z = originZ + row * cell;
+        const d = distanceAt(x, z);
+        const value = d < radiusMin - PRUNE
+            ? d - radiusMin
+            : d > radiusMax + PRUNE
+                ? d - radiusMax
+                : d - radiusAt(x, z) || 1e-6;
+        inside[index] = value;
+        return value;
+    };
+    const positions = [];
+    const drops = [];
+    const indices = [];
+    // Each wall's facing, summed over the walls that share an end so the contour shades smoothly.
+    const facing = new Map();
+    const ends = [];
+    const key = (x, z) => `${Math.round(x * 1e4)},${Math.round(z * 1e4)}`;
+    const lean = (at, nx, nz) => {
+        const sum = facing.get(at);
+        if (sum) {
+            sum[0] += nx;
+            sum[1] += nz;
+        }
+        else
+            facing.set(at, [nx, nz]);
+    };
+    let segments = 0;
+    const emit = (px, pz, qx, qz, nx, nz) => {
+        // Facing: the geometric normal of (top p, top q, foot q) is (dz, 0, -dx).
+        let ax = px;
+        let az = pz;
+        let bx = qx;
+        let bz = qz;
+        if (nx * (bz - az) - nz * (bx - ax) < 0) {
+            ax = qx;
+            az = qz;
+            bx = px;
+            bz = pz;
+        }
+        const base = positions.length / 3;
+        const ay = topAt(ax, az);
+        const by = topAt(bx, bz);
+        for (let row = 0; row <= PIT_WALL_ROWS; row += 1) {
+            positions.push(ax, ay, az, bx, by, bz);
+            drops.push(row / PIT_WALL_ROWS, row / PIT_WALL_ROWS);
+        }
+        const first = key(ax, az);
+        const second = key(bx, bz);
+        lean(first, nx, nz);
+        lean(second, nx, nz);
+        ends.push([first, second]);
+        for (let row = 0; row < PIT_WALL_ROWS; row += 1) {
+            const at = base + row * 2;
+            indices.push(at, at + 1, at + 3, at, at + 3, at + 2);
+        }
+        segments += 1;
+    };
+    // Blocks of cells whose centre is far from the whole range hold no contour: skipped unseen.
+    const skipBelow = radiusMin - PRUNE - BLOCK * cell * Math.SQRT1_2;
+    const skipAbove = radiusMax + PRUNE + BLOCK * cell * Math.SQRT1_2;
+    const blocks = Math.ceil(n / BLOCK);
+    const farMemo = new Int8Array(blocks * blocks);
+    const farBlock = (col, row) => {
+        const index = (row / BLOCK) * blocks + col / BLOCK;
+        if (farMemo[index] === 0) {
+            const d = distanceAt(originX + (col + BLOCK / 2) * cell, originZ + (row + BLOCK / 2) * cell);
+            farMemo[index] = d < skipBelow || d > skipAbove ? 1 : 2;
+        }
+        return farMemo[index] === 1;
+    };
+    for (let row = 0; row < n && segments < MAX_SEGMENTS; row += 1) {
+        for (let col = 0; col < n; col += 1) {
+            if (col % BLOCK === 0 && farBlock(col, row - (row % BLOCK))) {
+                col += BLOCK - 1;
+                continue;
+            }
+            const f0 = field(col, row);
+            const f1 = field(col + 1, row);
+            const f2 = field(col + 1, row + 1);
+            const f3 = field(col, row + 1);
+            const index = (f0 < 0 ? 1 : 0) | (f1 < 0 ? 2 : 0) | (f2 < 0 ? 4 : 0) | (f3 < 0 ? 8 : 0);
+            if (index === 0 || index === 15)
+                continue;
+            const x0 = originX + col * cell;
+            const z0 = originZ + row * cell;
+            const crossing = (edge) => {
+                switch (edge) {
+                    case 0:
+                        return [x0 + (cell * f0) / (f0 - f1), z0];
+                    case 1:
+                        return [x0 + cell, z0 + (cell * f1) / (f1 - f2)];
+                    case 2:
+                        return [x0 + cell - (cell * f2) / (f2 - f3), z0 + cell];
+                    default:
+                        return [x0, z0 + cell - (cell * f3) / (f3 - f0)];
+                }
+            };
+            let pairs = CASES[index];
+            if (index === 5 || index === 10) {
+                const centre = (f0 + f1 + f2 + f3) / 4 < 0;
+                pairs =
+                    index === 5
+                        ? centre
+                            ? [
+                                [0, 1],
+                                [2, 3],
+                            ]
+                            : [
+                                [3, 0],
+                                [1, 2],
+                            ]
+                        : centre
+                            ? [
+                                [3, 0],
+                                [1, 2],
+                            ]
+                            : [
+                                [0, 1],
+                                [2, 3],
+                            ];
+            }
+            for (const [ea, eb] of pairs) {
+                const [px, pz] = crossing(ea);
+                const [qx, qz] = crossing(eb);
+                const dx = qx - px;
+                const dz = qz - pz;
+                const length = Math.hypot(dx, dz);
+                if (length < 1e-6)
+                    continue;
+                // The wall faces into the hole: probe the cell's bilinear field a little off the segment.
+                let nx = dz / length;
+                let nz = -dx / length;
+                const probeX = ((px + qx) / 2 + nx * cell * 0.3 - x0) / cell;
+                const probeZ = ((pz + qz) / 2 + nz * cell * 0.3 - z0) / cell;
+                const bilinear = f0 * (1 - probeX) * (1 - probeZ) +
+                    f1 * probeX * (1 - probeZ) +
+                    f3 * (1 - probeX) * probeZ +
+                    f2 * probeX * probeZ;
+                if (bilinear >= 0) {
+                    nx = -nx;
+                    nz = -nz;
+                }
+                emit(px, pz, qx, qz, nx, nz);
+            }
+        }
+    }
+    if (segments === 0)
+        return null;
+    const normals = new Float32Array(positions.length);
+    ends.forEach(([first, second], quad) => {
+        for (let slot = 0; slot < PIT_WALL_ROWS * 2 + 2; slot += 1) {
+            const [nx, nz] = facing.get(slot % 2 === 0 ? first : second);
+            const length = Math.hypot(nx, nz) || 1;
+            normals.set([nx / length, 0, nz / length], (quad * (PIT_WALL_ROWS * 2 + 2) + slot) * 3);
+        }
+    });
+    return {
+        positions: new Float32Array(positions),
+        normals,
+        drops: new Float32Array(drops),
+        indices: new Uint32Array(indices),
+    };
+}