@pascal-app/nodes 0.1.1 → 1.0.0-beta.2

package/dist/site/terrain-geometry.d.ts

@@ -0,0 +1,131 @@
+import { type HeightPatch, type TerrainField } from '@pascal-app/core';
+/**
+ * Builds the terrain mesh buffers from a `TerrainField`.
+ *
+ * Split out of the renderer as pure array math so the vertex layout is
+ * unit-testable without a canvas, and so the partial-upload path has one
+ * definition. The renderer owns the `BufferGeometry`; this owns what goes in it.
+ *
+ * The triangulation this file emits is the convention `surfaceHeightAt`
+ * (`core/lib/terrain-field.ts`) reads back: two triangles per cell split along the
+ * `(c+1,r)`–`(c,r+1)` diagonal. Anything drawn *on* the ground samples that
+ * function, so changing the winding below without changing it there would make
+ * every draped line sink into half of every cell.
+ *
+ * Two rules that are easy to get wrong and expensive to debug:
+ *
+ * - **Normals are analytic, never `computeVertexNormals()`.** Beyond the cost
+ *   (~1.5 ms at 257²), `computeVertexNormals()` rewrites the *whole* normal
+ *   attribute, which silently defeats the dirty-rect partial upload that makes
+ *   sculpting cheap. `normalAt` central-differences the field instead, so a
+ *   patch touches only the rows it changed.
+ * - **Vertices are one-per-sample and shared between triangles**, so a partial
+ *   upload is a contiguous row range. Duplicating verts per-triangle for flat
+ *   shading would triple memory and scatter the dirty range.
+ */
+/**
+ * Y of the site's presentation horizon disc (`site/renderer.tsx`).
+ *
+ * It lives here, next to the skirt, because the skirt is the thing that has to
+ * bracket it: its top edge never sits below this plane and its base always clears
+ * it, so no sightline can pass between the sculpted ground and the surrounding
+ * one. Two readers, one number.
+ */
+export declare const HORIZON_PLANE_Y = -0.07;
+/** One vertex per sample, row-major — index `r * cols + c` matches the field. */
+export type TerrainMeshBuffers = {
+    /** xyz per sample, length `cols * rows * 3`. */
+    positions: Float32Array;
+    /** xyz per sample, length `cols * rows * 3`. */
+    normals: Float32Array;
+    /** uv per sample, length `cols * rows * 2`. */
+    uvs: Float32Array;
+    /** Triangle indices, two per grid cell. */
+    indices: Uint32Array;
+};
+export declare function buildTerrainMesh(field: TerrainField): TerrainMeshBuffers;
+/**
+ * A vertical curtain around the field boundary, closing the terrain against the
+ * site's horizon disc.
+ *
+ * The disc is a flat plate at `HORIZON_PLANE_Y` standing in for ground beyond the
+ * field, and the field's extent is punched out of it so an excavation is not simply
+ * hidden under it. That punch leaves an open rim, and sculpted ground turns it into
+ * a visible fault: a raised edge shows daylight under the terrain shell, a lowered
+ * one shows the disc's cut edge hanging in the air over the pit.
+ *
+ * The curtain spans `[min(h, H) - SKIRT_DROP, max(h, H)]` at every boundary
+ * sample, so it *brackets* both the terrain edge and the horizon plane no matter
+ * which is higher. That is the whole correctness argument: a sightline through the
+ * rim has to cross the curtain, because the curtain covers the rim's entire Y
+ * range at the rim's exact XZ.
+ *
+ * One vertex pair (top, bottom) per boundary sample, in a ring whose first sample
+ * is repeated at the end so the strip closes.
+ */
+export type TerrainSkirtBuffers = {
+    /** xyz, `(perimeter + 1) * 2` vertices — top then bottom per ring position. */
+    positions: Float32Array;
+    normals: Float32Array;
+    indices: Uint32Array;
+};
+/**
+ * The field's own footprint, as a polygon to punch out of the horizon disc.
+ *
+ * The punch is the only reason an excavation is visible at all: without it the disc
+ * — a flat plate at `HORIZON_PLANE_Y` standing in for ground beyond the field —
+ * roofs over every pit, so digging a basement reads as no change whatsoever. On
+ * raised or flat ground it costs nothing visually, because the terrain shell and its
+ * skirt cover the hole from both sides.
+ *
+ * Inset by half a cell, so the disc and the terrain edge *overlap* rather than meet:
+ * two coplanar edges at exactly the same XZ z-fight along the whole perimeter. The
+ * inset is what the skirt's bracketing span is covering, which is why this lives
+ * beside `buildTerrainSkirt` — the two have to agree about where the rim is, and a
+ * footprint that punched wider than the skirt spans would open a gap the skirt never
+ * closes.
+ *
+ * Kept here rather than in the renderer so it is reachable without Three.js: it
+ * decides whether a pit is visible, and that is a property to assert, not to eyeball.
+ */
+export declare function terrainFootprint(field: TerrainField): Array<[number, number]>;
+export declare function buildTerrainSkirt(field: TerrainField): TerrainSkirtBuffers;
+/**
+ * Rewrite the whole skirt in place.
+ *
+ * Whole, not dirty-ranged, unlike the surface: the perimeter is `2(cols + rows)`
+ * vertices — 1 028 at 257², under 3% of the surface's vertex count — so the
+ * bookkeeping to find which boundary samples a rectangular patch touched costs
+ * more than re-uploading all of them. The surface's dirty range earns its
+ * complexity because it saves 400 KB a dab; here there is nothing to save.
+ */
+export declare function updateTerrainSkirt(field: TerrainField, buffers: TerrainSkirtBuffers): void;
+/**
+ * The contiguous vertex range a patch dirties, in **array elements** — the unit
+ * `BufferAttribute.addUpdateRange(start, count)` expects.
+ *
+ * A patch is rectangular, so the touched vertices are not contiguous unless the
+ * patch spans full rows. Rather than issue one range per row, this returns the
+ * single span from the patch's first vertex to its last: over-reporting a few
+ * clean vertices is far cheaper than many small GPU uploads, and it keeps the
+ * caller to one `addUpdateRange` call.
+ *
+ * The range is widened by one row on each side because a height change moves the
+ * *normals* of its neighbours too (central differences reach one sample out).
+ * Getting this wrong produces the classic symptom: correct silhouette, stale
+ * shading along the edit boundary.
+ */
+export declare function patchUpdateRange(field: TerrainField, patch: HeightPatch, itemSize: number): {
+    start: number;
+    count: number;
+} | null;
+/**
+ * Rewrites only the vertices a patch touched, in place.
+ *
+ * Takes the *already-patched* field (the one `applyHeightPatch` returned) and
+ * the patch that produced it, so the caller cannot accidentally rebuild from
+ * stale heights. Mutates the buffers rather than reallocating — that is the
+ * whole point of the dirty-rect path.
+ */
+export declare function updateTerrainMesh(field: TerrainField, buffers: TerrainMeshBuffers, patch: HeightPatch): void;
+//# sourceMappingURL=terrain-geometry.d.ts.map

package/dist/site/terrain-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-geometry.d.ts","sourceRoot":"","sources":["../../src/site/terrain-geometry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAA4B,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAEhG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAAQ,CAAA;AAWpC,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gDAAgD;IAChD,SAAS,EAAE,YAAY,CAAA;IACvB,gDAAgD;IAChD,OAAO,EAAE,YAAY,CAAA;IACrB,+CAA+C;IAC/C,GAAG,EAAE,YAAY,CAAA;IACjB,2CAA2C;IAC3C,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAOD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,kBAAkB,CAkCxE;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,+EAA+E;IAC/E,SAAS,EAAE,YAAY,CAAA;IACvB,OAAO,EAAE,YAAY,CAAA;IACrB,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY7E;AAwBD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAsB1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAyB1F;AAmBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAWzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,WAAW,GACjB,IAAI,CASN"}

package/dist/site/terrain-geometry.js

@@ -0,0 +1,259 @@
+import { heightAtSample, normalAt } from '@pascal-app/core';
+/**
+ * Builds the terrain mesh buffers from a `TerrainField`.
+ *
+ * Split out of the renderer as pure array math so the vertex layout is
+ * unit-testable without a canvas, and so the partial-upload path has one
+ * definition. The renderer owns the `BufferGeometry`; this owns what goes in it.
+ *
+ * The triangulation this file emits is the convention `surfaceHeightAt`
+ * (`core/lib/terrain-field.ts`) reads back: two triangles per cell split along the
+ * `(c+1,r)`–`(c,r+1)` diagonal. Anything drawn *on* the ground samples that
+ * function, so changing the winding below without changing it there would make
+ * every draped line sink into half of every cell.
+ *
+ * Two rules that are easy to get wrong and expensive to debug:
+ *
+ * - **Normals are analytic, never `computeVertexNormals()`.** Beyond the cost
+ *   (~1.5 ms at 257²), `computeVertexNormals()` rewrites the *whole* normal
+ *   attribute, which silently defeats the dirty-rect partial upload that makes
+ *   sculpting cheap. `normalAt` central-differences the field instead, so a
+ *   patch touches only the rows it changed.
+ * - **Vertices are one-per-sample and shared between triangles**, so a partial
+ *   upload is a contiguous row range. Duplicating verts per-triangle for flat
+ *   shading would triple memory and scatter the dirty range.
+ */
+/**
+ * Y of the site's presentation horizon disc (`site/renderer.tsx`).
+ *
+ * It lives here, next to the skirt, because the skirt is the thing that has to
+ * bracket it: its top edge never sits below this plane and its base always clears
+ * it, so no sightline can pass between the sculpted ground and the surrounding
+ * one. Two readers, one number.
+ */
+export const HORIZON_PLANE_Y = -0.07;
+/**
+ * How far the skirt's base hangs below the lowest thing it must close over.
+ *
+ * Only the top edge is visually load-bearing; the base just has to be out of sight
+ * under the horizon disc. A metre reads as earth thickness from a grazing camera
+ * without being tall enough to poke out of a neighbouring excavation.
+ */
+const SKIRT_DROP = 1;
+/** Vertex index of sample [c,r]. */
+function vertexIndex(field, col, row) {
+    return row * field.cols + col;
+}
+export function buildTerrainMesh(field) {
+    const count = field.cols * field.rows;
+    const positions = new Float32Array(count * 3);
+    const normals = new Float32Array(count * 3);
+    const uvs = new Float32Array(count * 2);
+    for (let r = 0; r < field.rows; r++) {
+        for (let c = 0; c < field.cols; c++) {
+            const i = r * field.cols + c;
+            writeVertex(field, positions, normals, uvs, c, r, i);
+        }
+    }
+    // Two triangles per cell. Winding is counter-clockwise seen from +Y so the
+    // surface faces up under the default FrontSide material.
+    const cells = (field.cols - 1) * (field.rows - 1);
+    const indices = new Uint32Array(Math.max(0, cells) * 6);
+    let n = 0;
+    for (let r = 0; r < field.rows - 1; r++) {
+        for (let c = 0; c < field.cols - 1; c++) {
+            const a = vertexIndex(field, c, r);
+            const b = vertexIndex(field, c + 1, r);
+            const d = vertexIndex(field, c, r + 1);
+            const e = vertexIndex(field, c + 1, r + 1);
+            indices[n++] = a;
+            indices[n++] = d;
+            indices[n++] = b;
+            indices[n++] = b;
+            indices[n++] = d;
+            indices[n++] = e;
+        }
+    }
+    return { positions, normals, uvs, indices };
+}
+function writeVertex(field, positions, normals, uvs, col, row, index) {
+    const x = field.origin[0] + col * field.spacing;
+    const z = field.origin[1] + row * field.spacing;
+    const y = heightAtSample(field, col, row);
+    positions[index * 3] = x;
+    positions[index * 3 + 1] = y;
+    positions[index * 3 + 2] = z;
+    const [nx, ny, nz] = normalAt(field, x, z);
+    normals[index * 3] = nx;
+    normals[index * 3 + 1] = ny;
+    normals[index * 3 + 2] = nz;
+    // UVs span the field 0..1 so a tiled ground material scales with the site
+    // rather than with sample count.
+    uvs[index * 2] = field.cols > 1 ? col / (field.cols - 1) : 0;
+    uvs[index * 2 + 1] = field.rows > 1 ? row / (field.rows - 1) : 0;
+}
+/**
+ * The field's own footprint, as a polygon to punch out of the horizon disc.
+ *
+ * The punch is the only reason an excavation is visible at all: without it the disc
+ * — a flat plate at `HORIZON_PLANE_Y` standing in for ground beyond the field —
+ * roofs over every pit, so digging a basement reads as no change whatsoever. On
+ * raised or flat ground it costs nothing visually, because the terrain shell and its
+ * skirt cover the hole from both sides.
+ *
+ * Inset by half a cell, so the disc and the terrain edge *overlap* rather than meet:
+ * two coplanar edges at exactly the same XZ z-fight along the whole perimeter. The
+ * inset is what the skirt's bracketing span is covering, which is why this lives
+ * beside `buildTerrainSkirt` — the two have to agree about where the rim is, and a
+ * footprint that punched wider than the skirt spans would open a gap the skirt never
+ * closes.
+ *
+ * Kept here rather than in the renderer so it is reachable without Three.js: it
+ * decides whether a pit is visible, and that is a property to assert, not to eyeball.
+ */
+export function terrainFootprint(field) {
+    const inset = field.spacing / 2;
+    const minX = field.origin[0] + inset;
+    const minZ = field.origin[1] + inset;
+    const maxX = field.origin[0] + (field.cols - 1) * field.spacing - inset;
+    const maxZ = field.origin[1] + (field.rows - 1) * field.spacing - inset;
+    return [
+        [minX, minZ],
+        [maxX, minZ],
+        [maxX, maxZ],
+        [minX, maxZ],
+    ];
+}
+/** Boundary sample count — a function of the grid shape alone. */
+function perimeterCount(field) {
+    if (field.cols < 2 || field.rows < 2)
+        return 0;
+    return 2 * (field.cols - 1) + 2 * (field.rows - 1);
+}
+/**
+ * The `i`th boundary sample, walking top → right → bottom → left.
+ *
+ * The direction matters: traversed this way the outward horizontal is the tangent
+ * rotated as `(tx, tz) → (tz, -tx)` on every edge, which is what makes one winding
+ * rule and one normal formula cover all four sides instead of four special cases.
+ */
+function boundarySample(field, i) {
+    const lastCol = field.cols - 1;
+    const lastRow = field.rows - 1;
+    if (i < lastCol)
+        return { col: i, row: 0 };
+    if (i < lastCol + lastRow)
+        return { col: lastCol, row: i - lastCol };
+    if (i < 2 * lastCol + lastRow)
+        return { col: 2 * lastCol + lastRow - i, row: lastRow };
+    return { col: 0, row: 2 * (lastCol + lastRow) - i };
+}
+export function buildTerrainSkirt(field) {
+    const count = perimeterCount(field);
+    const vertices = count === 0 ? 0 : (count + 1) * 2;
+    const buffers = {
+        positions: new Float32Array(vertices * 3),
+        normals: new Float32Array(vertices * 3),
+        indices: new Uint32Array(count * 6),
+    };
+    for (let i = 0; i < count; i++) {
+        const base = i * 6;
+        const top = i * 2;
+        const nextTop = (i + 1) * 2;
+        // Outward faces front: see the winding note on `buildTerrainMesh`.
+        buffers.indices[base] = top;
+        buffers.indices[base + 1] = nextTop;
+        buffers.indices[base + 2] = top + 1;
+        buffers.indices[base + 3] = top + 1;
+        buffers.indices[base + 4] = nextTop;
+        buffers.indices[base + 5] = nextTop + 1;
+    }
+    updateTerrainSkirt(field, buffers);
+    return buffers;
+}
+/**
+ * Rewrite the whole skirt in place.
+ *
+ * Whole, not dirty-ranged, unlike the surface: the perimeter is `2(cols + rows)`
+ * vertices — 1 028 at 257², under 3% of the surface's vertex count — so the
+ * bookkeeping to find which boundary samples a rectangular patch touched costs
+ * more than re-uploading all of them. The surface's dirty range earns its
+ * complexity because it saves 400 KB a dab; here there is nothing to save.
+ */
+export function updateTerrainSkirt(field, buffers) {
+    const count = perimeterCount(field);
+    if (count === 0)
+        return;
+    for (let i = 0; i <= count; i++) {
+        const { col, row } = boundarySample(field, i % count);
+        const x = field.origin[0] + col * field.spacing;
+        const z = field.origin[1] + row * field.spacing;
+        const h = heightAtSample(field, col, row);
+        const previous = boundarySample(field, (i - 1 + count) % count);
+        const next = boundarySample(field, (i + 1) % count);
+        // Tangent across the neighbours, so a corner gets the bevelled average of its
+        // two edges rather than one of them arbitrarily.
+        const tx = next.col - previous.col;
+        const tz = next.row - previous.row;
+        const tLength = Math.hypot(tx, tz) || 1;
+        const nx = tz / tLength;
+        const nz = -tx / tLength;
+        const topIndex = i * 2;
+        const bottomIndex = topIndex + 1;
+        writeSkirtVertex(buffers, topIndex, x, Math.max(h, HORIZON_PLANE_Y), z, nx, nz);
+        writeSkirtVertex(buffers, bottomIndex, x, Math.min(h, HORIZON_PLANE_Y) - SKIRT_DROP, z, nx, nz);
+    }
+}
+function writeSkirtVertex(buffers, index, x, y, z, nx, nz) {
+    buffers.positions[index * 3] = x;
+    buffers.positions[index * 3 + 1] = y;
+    buffers.positions[index * 3 + 2] = z;
+    buffers.normals[index * 3] = nx;
+    buffers.normals[index * 3 + 1] = 0;
+    buffers.normals[index * 3 + 2] = nz;
+}
+/**
+ * The contiguous vertex range a patch dirties, in **array elements** — the unit
+ * `BufferAttribute.addUpdateRange(start, count)` expects.
+ *
+ * A patch is rectangular, so the touched vertices are not contiguous unless the
+ * patch spans full rows. Rather than issue one range per row, this returns the
+ * single span from the patch's first vertex to its last: over-reporting a few
+ * clean vertices is far cheaper than many small GPU uploads, and it keeps the
+ * caller to one `addUpdateRange` call.
+ *
+ * The range is widened by one row on each side because a height change moves the
+ * *normals* of its neighbours too (central differences reach one sample out).
+ * Getting this wrong produces the classic symptom: correct silhouette, stale
+ * shading along the edit boundary.
+ */
+export function patchUpdateRange(field, patch, itemSize) {
+    const firstRow = Math.max(0, patch.row0 - 1);
+    const lastRow = Math.min(field.rows - 1, patch.row0 + patch.rows);
+    if (lastRow < firstRow)
+        return null;
+    const startVertex = firstRow * field.cols;
+    const endVertex = lastRow * field.cols + (field.cols - 1);
+    return {
+        start: startVertex * itemSize,
+        count: (endVertex - startVertex + 1) * itemSize,
+    };
+}
+/**
+ * Rewrites only the vertices a patch touched, in place.
+ *
+ * Takes the *already-patched* field (the one `applyHeightPatch` returned) and
+ * the patch that produced it, so the caller cannot accidentally rebuild from
+ * stale heights. Mutates the buffers rather than reallocating — that is the
+ * whole point of the dirty-rect path.
+ */
+export function updateTerrainMesh(field, buffers, patch) {
+    const firstRow = Math.max(0, patch.row0 - 1);
+    const lastRow = Math.min(field.rows - 1, patch.row0 + patch.rows);
+    for (let r = firstRow; r <= lastRow; r++) {
+        for (let c = 0; c < field.cols; c++) {
+            const i = r * field.cols + c;
+            writeVertex(field, buffers.positions, buffers.normals, buffers.uvs, c, r, i);
+        }
+    }
+}

package/dist/site/terrain-mesh.d.ts

@@ -0,0 +1,49 @@
+import type { HeightPatch, TerrainField } from '@pascal-app/core';
+import { BufferGeometry } from 'three';
+import { type TerrainMeshBuffers, type TerrainSkirtBuffers } from './terrain-geometry';
+/**
+ * The Three.js side of the terrain heightfield: owns the `BufferGeometry` and the
+ * dirty-rect upload.
+ *
+ * Kept beside the pure builder rather than in `viewer` because the dependency
+ * runs `nodes -> viewer`, not the other way, and this is a per-kind concern
+ * anyway. `terrain-geometry.ts` computes *what* goes in the buffers (testable
+ * without a canvas); this owns the GPU resource. The only thing that cannot live
+ * on the pure side is `addUpdateRange`/`needsUpdate`, which is why this file is
+ * thin.
+ *
+ * Why patch instead of rebuild: a 129² field is 16 641 vertices, so a full
+ * re-upload is ~400 KB per dab. There is no render-on-demand to hide behind —
+ * `FrameLimiter` runs a perpetual rAF at 50 FPS — so a brush dragged across a
+ * slope would re-upload the whole field dozens of times a second.
+ */
+/** A terrain geometry plus the CPU buffers backing it. */
+export type TerrainGeometry = {
+    readonly geometry: BufferGeometry;
+    readonly buffers: TerrainMeshBuffers;
+    /** The edge curtain that closes the field against the horizon disc. */
+    readonly skirt: {
+        readonly geometry: BufferGeometry;
+        readonly buffers: TerrainSkirtBuffers;
+    };
+};
+export declare function createTerrainGeometry(field: TerrainField): TerrainGeometry;
+/**
+ * Push one patch to the GPU, touching only the affected rows.
+ *
+ * Both `position` and `normal` are updated: a height change moves its
+ * neighbours' normals too, and `patchUpdateRange` already widens the span by one
+ * row on each side to cover that. UVs are never touched — they are a function of
+ * grid indices, not heights.
+ */
+export declare function applyTerrainPatch(target: TerrainGeometry, field: TerrainField, patch: HeightPatch): void;
+/**
+ * True when a geometry was built for a differently-shaped field.
+ *
+ * A resized field cannot be patched — the vertex count changed — so the caller
+ * must rebuild. Checking here keeps that decision in one place instead of every
+ * caller comparing `cols`/`rows` by hand.
+ */
+export declare function needsRebuild(target: TerrainGeometry, field: TerrainField): boolean;
+export declare function disposeTerrainGeometry(target: TerrainGeometry): void;
+//# sourceMappingURL=terrain-mesh.d.ts.map

package/dist/site/terrain-mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-mesh.d.ts","sourceRoot":"","sources":["../../src/site/terrain-mesh.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAmB,cAAc,EAAmB,MAAM,OAAO,CAAA;AACxE,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EAGzB,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;;;;;;GAeG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;IACpC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;KAAE,CAAA;CAC7F,CAAA;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAoB1E;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,WAAW,GACjB,IAAI,CA0BN;AA8DD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAElF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAGpE"}

package/dist/site/terrain-mesh.js

@@ -0,0 +1,122 @@
+import { BufferAttribute, BufferGeometry, Sphere, Vector3 } from 'three';
+import { buildTerrainMesh, buildTerrainSkirt, HORIZON_PLANE_Y, patchUpdateRange, updateTerrainMesh, updateTerrainSkirt, } from './terrain-geometry';
+export function createTerrainGeometry(field) {
+    const buffers = buildTerrainMesh(field);
+    const geometry = new BufferGeometry();
+    geometry.setAttribute('position', new BufferAttribute(buffers.positions, 3));
+    geometry.setAttribute('normal', new BufferAttribute(buffers.normals, 3));
+    geometry.setAttribute('uv', new BufferAttribute(buffers.uvs, 2));
+    geometry.setIndex(new BufferAttribute(buffers.indices, 1));
+    setTerrainBounds(geometry, field);
+    // A separate geometry, not extra vertices on the surface: the surface's dirty
+    // range is a row span over a `cols * rows` layout, and appending a perimeter ring
+    // to it would break that indexing for a saving of one draw call.
+    const skirtBuffers = buildTerrainSkirt(field);
+    const skirtGeometry = new BufferGeometry();
+    skirtGeometry.setAttribute('position', new BufferAttribute(skirtBuffers.positions, 3));
+    skirtGeometry.setAttribute('normal', new BufferAttribute(skirtBuffers.normals, 3));
+    skirtGeometry.setIndex(new BufferAttribute(skirtBuffers.indices, 1));
+    setSkirtBounds(skirtGeometry, field);
+    return { geometry, buffers, skirt: { geometry: skirtGeometry, buffers: skirtBuffers } };
+}
+/**
+ * Push one patch to the GPU, touching only the affected rows.
+ *
+ * Both `position` and `normal` are updated: a height change moves its
+ * neighbours' normals too, and `patchUpdateRange` already widens the span by one
+ * row on each side to cover that. UVs are never touched — they are a function of
+ * grid indices, not heights.
+ */
+export function applyTerrainPatch(target, field, patch) {
+    updateTerrainMesh(field, target.buffers, patch);
+    // The skirt goes up unconditionally, before the range bail: a patch that leaves
+    // the surface's dirty span empty can still have moved a boundary sample, and a
+    // stale skirt is a hole at the property line.
+    updateTerrainSkirt(field, target.skirt.buffers);
+    for (const name of ['position', 'normal']) {
+        const attribute = target.skirt.geometry.getAttribute(name);
+        attribute.needsUpdate = true;
+    }
+    setSkirtBounds(target.skirt.geometry, field);
+    const range = patchUpdateRange(field, patch, 3);
+    if (!range)
+        return;
+    for (const name of ['position', 'normal']) {
+        const attribute = target.geometry.getAttribute(name);
+        // `clearUpdateRanges` first: ranges accumulate, so a stroke dabbing 60 times
+        // a second would otherwise grow an unbounded list that all gets re-uploaded.
+        attribute.clearUpdateRanges();
+        attribute.addUpdateRange(range.start, range.count);
+        attribute.needsUpdate = true;
+    }
+    setTerrainBounds(target.geometry, field);
+}
+/**
+ * Set bounds analytically instead of calling `computeBoundingSphere()`.
+ *
+ * The computed version walks every vertex twice and allocates; the field's
+ * horizontal extent is known in O(1) from `origin`/`spacing`/`cols`/`rows`, and
+ * only the height range needs a scan. Skipping bounds entirely is not an option —
+ * a stale bounding sphere gets a raised hill frustum-culled while it is still on
+ * screen, which reads as terrain flickering out at certain camera angles.
+ */
+function setTerrainBounds(geometry, field) {
+    const { minY, maxY } = heightSpan(field);
+    const minX = field.origin[0];
+    const minZ = field.origin[1];
+    const maxX = minX + (field.cols - 1) * field.spacing;
+    const maxZ = minZ + (field.rows - 1) * field.spacing;
+    const center = new Vector3((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+    const radius = Math.hypot((maxX - minX) / 2, (maxY - minY) / 2, (maxZ - minZ) / 2);
+    geometry.boundingSphere = new Sphere(center, radius);
+    if (geometry.boundingBox) {
+        geometry.boundingBox.set(new Vector3(minX, minY, minZ), new Vector3(maxX, maxY, maxZ));
+    }
+}
+/**
+ * Bounds for the skirt, which hangs below the field's own low point.
+ *
+ * Reusing `setTerrainBounds` would cull the curtain the moment its top edge left
+ * the surface's sphere — the exact symptom the surface's analytic bounds exist to
+ * avoid, one geometry over. The vertical span brackets the horizon plane for the
+ * same reason the geometry does.
+ */
+function setSkirtBounds(geometry, field) {
+    const { minY, maxY } = heightSpan(field);
+    const low = Math.min(minY, HORIZON_PLANE_Y) - 1;
+    const high = Math.max(maxY, HORIZON_PLANE_Y);
+    const minX = field.origin[0];
+    const minZ = field.origin[1];
+    const maxX = minX + (field.cols - 1) * field.spacing;
+    const maxZ = minZ + (field.rows - 1) * field.spacing;
+    const center = new Vector3((minX + maxX) / 2, (low + high) / 2, (minZ + maxZ) / 2);
+    const radius = Math.hypot((maxX - minX) / 2, (high - low) / 2, (maxZ - minZ) / 2);
+    geometry.boundingSphere = new Sphere(center, radius);
+}
+/** Height span in metres, always including the datum so flat ground has a box. */
+function heightSpan(field) {
+    let minH = 0;
+    let maxH = 0;
+    for (let i = 0; i < field.heights.length; i++) {
+        const h = field.heights[i] ?? 0;
+        if (h < minH)
+            minH = h;
+        if (h > maxH)
+            maxH = h;
+    }
+    return { minY: minH * field.step, maxY: maxH * field.step };
+}
+/**
+ * True when a geometry was built for a differently-shaped field.
+ *
+ * A resized field cannot be patched — the vertex count changed — so the caller
+ * must rebuild. Checking here keeps that decision in one place instead of every
+ * caller comparing `cols`/`rows` by hand.
+ */
+export function needsRebuild(target, field) {
+    return target.buffers.positions.length !== field.cols * field.rows * 3;
+}
+export function disposeTerrainGeometry(target) {
+    target.geometry.dispose();
+    target.skirt.geometry.dispose();
+}

package/dist/site/terrain-renderer.d.ts

@@ -0,0 +1,28 @@
+import { type SiteNode } from '@pascal-app/core';
+import type { Material } from 'three';
+/**
+ * Renders the site's sculpted ground.
+ *
+ * Mounted by `SiteRenderer` only when the site has terrain (or a stroke is in
+ * flight), so a scene that never touched terrain mounts nothing at all and pays
+ * nothing.
+ *
+ * Two things here are load-bearing and easy to get wrong:
+ *
+ * - **The geometry is a ref, not React state.** A sculpt stroke pushes dozens of
+ *   patches a second; routing each through a re-render would rebuild the
+ *   `BufferGeometry` object identity every dab and throw away the partial-upload
+ *   win entirely. The component subscribes to the *patch*, mutates the buffers in
+ *   place, and never re-renders during a stroke.
+ * - **It stays on the default `SCENE_LAYER`.** This is real, visible,
+ *   shadow-receiving geometry — not an overlay. Overlay/hit-area meshes must use
+ *   the editor layer, but moving actual scene geometry there would exclude it from
+ *   the MRT depth/normal pass and break the screen-space ink against it.
+ */
+export declare const TerrainRenderer: ({ material, site, }: {
+    /** Owned by `SiteRenderer` so the ground material stays defined in one place. */
+    material: Material;
+    site: SiteNode;
+}) => import("react").JSX.Element | null;
+export default TerrainRenderer;
+//# sourceMappingURL=terrain-renderer.d.ts.map

package/dist/site/terrain-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-renderer.d.ts","sourceRoot":"","sources":["../../src/site/terrain-renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,QAAQ,EAAkC,MAAM,kBAAkB,CAAA;AAEhF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AASrC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,GAAI,qBAG7B;IACD,iFAAiF;IACjF,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,QAAQ,CAAA;CACf,uCA6DA,CAAA;AAED,eAAe,eAAe,CAAA"}

package/dist/site/terrain-renderer.js

@@ -0,0 +1,69 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { terrainFieldOf, useLiveTerrain } from '@pascal-app/core';
+import { useEffect, useMemo, useRef } from 'react';
+import { applyTerrainPatch, createTerrainGeometry, disposeTerrainGeometry, needsRebuild, } from './terrain-mesh';
+/**
+ * Renders the site's sculpted ground.
+ *
+ * Mounted by `SiteRenderer` only when the site has terrain (or a stroke is in
+ * flight), so a scene that never touched terrain mounts nothing at all and pays
+ * nothing.
+ *
+ * Two things here are load-bearing and easy to get wrong:
+ *
+ * - **The geometry is a ref, not React state.** A sculpt stroke pushes dozens of
+ *   patches a second; routing each through a re-render would rebuild the
+ *   `BufferGeometry` object identity every dab and throw away the partial-upload
+ *   win entirely. The component subscribes to the *patch*, mutates the buffers in
+ *   place, and never re-renders during a stroke.
+ * - **It stays on the default `SCENE_LAYER`.** This is real, visible,
+ *   shadow-receiving geometry — not an overlay. Overlay/hit-area meshes must use
+ *   the editor layer, but moving actual scene geometry there would exclude it from
+ *   the MRT depth/normal pass and break the screen-space ink against it.
+ */
+export const TerrainRenderer = ({ material, site, }) => {
+    const targetRef = useRef(null);
+    // Persisted terrain only — the live stroke is applied imperatively below, so a
+    // dab never triggers a React render.
+    const persistedField = useMemo(() => terrainFieldOf({ id: site.id, terrain: site.terrain }), [site.id, site.terrain]);
+    const target = useMemo(() => {
+        const field = useLiveTerrain.getState().fieldOf(site.id) ?? persistedField;
+        if (!field)
+            return null;
+        return createTerrainGeometry(field);
+    }, [persistedField, site.id]);
+    targetRef.current = target;
+    useEffect(() => () => {
+        if (target)
+            disposeTerrainGeometry(target);
+    }, [target]);
+    // Imperative subscription rather than a selector hook: the point is to react to
+    // a dab *without* re-rendering. Zustand's subscribe gives the previous state
+    // too, so a patch is only uploaded once even if an unrelated store update
+    // notifies.
+    useEffect(() => {
+        let lastPatch = useLiveTerrain.getState().strokeOf(site.id)?.lastPatch ?? null;
+        return useLiveTerrain.subscribe((state) => {
+            const stroke = state.strokes.get(site.id);
+            const current = targetRef.current;
+            if (!(stroke && current)) {
+                lastPatch = null;
+                return;
+            }
+            if (!stroke.lastPatch || stroke.lastPatch === lastPatch)
+                return;
+            lastPatch = stroke.lastPatch;
+            // A resized field cannot be patched — the vertex count changed. That only
+            // happens on import, never mid-stroke, so bail and let the persisted-field
+            // rebuild handle it rather than silently corrupting the buffers.
+            if (needsRebuild(current, stroke.field))
+                return;
+            applyTerrainPatch(current, stroke.field, stroke.lastPatch);
+        });
+    }, [site.id]);
+    if (!target)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx("mesh", { castShadow: true, geometry: target.geometry, material: material, receiveShadow: true }), _jsx("mesh", { geometry: target.skirt.geometry, material: material, receiveShadow: true })] }));
+};
+export default TerrainRenderer;