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

package/dist/shelf/tool.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { collectAlignmentAnchors, emitter, ShelfNode, useScene, } from '@pascal-app/core';
+import { collectAlignmentAnchors, emitter, resolveSupportSlabPatch, ShelfNode, useScene, } from '@pascal-app/core';
 import { getFloorStackPreviewPosition, isAlignmentGuideActive, isGridSnapActive, isMagneticSnapActive, movementSfxStepKey, triggerSFX, useAlignmentGuides, useEditor, } from '@pascal-app/editor';
 import { useViewer } from '@pascal-app/viewer';
 import { useEffect, useMemo, useRef, useState } from 'react';
@@ -92,9 +92,14 @@ const ShelfTool = () => {
                 name: 'Shelf',
                 position,
                 rotation: [0, 0, 0],
+                parentId: activeLevelId,
             });
-            useScene.getState().createNode(shelf, activeLevelId);
-            useViewer.getState().setSelection({ selectedIds: [shelf.id] });
+            const committedShelf = ShelfNode.parse({
+                ...shelf,
+                ...resolveSupportSlabPatch(shelf, useScene.getState().nodes),
+            });
+            useScene.getState().createNode(committedShelf, activeLevelId);
+            useViewer.getState().setSelection({ selectedIds: [committedShelf.id] });
             triggerSFX('sfx:item-place');
             useAlignmentGuides.getState().clear();
             if (useEditor.getState().getContinuation('point') === 'repeat') {

package/dist/site/recessed-slab-ground-holes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recessed-slab-ground-holes.d.ts","sourceRoot":"","sources":["../../src/site/recessed-slab-ground-holes.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,kBAAkB,CAAA;AAEzB,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CA8ChC"}
+{"version":3,"file":"recessed-slab-ground-holes.d.ts","sourceRoot":"","sources":["../../src/site/recessed-slab-ground-holes.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAKb,MAAM,kBAAkB,CAAA;AAEzB,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CA2ChC"}

package/dist/site/recessed-slab-ground-holes.js

@@ -25,10 +25,7 @@ export function getRecessedSlabGroundHoles(nodes) {
             pushByLevel(slabsByLevel, levelId, node);
     }
     return nodeList
-        .filter((node) => node.type === 'slab' &&
-        node.visible &&
-        node.polygon.length >= 3 &&
-        (node.elevation ?? 0.05) < 0)
+        .filter((node) => node.type === 'slab' && node.visible && node.polygon.length >= 3 && node.recessed === true)
         .filter((slab) => {
         if (!Number.isFinite(lowestLevelIndex))
             return true;

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

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/site/renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,QAAQ,EAId,MAAM,kBAAkB,CAAA;AAkGzB,eAAO,MAAM,YAAY,GAAI,UAAU;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,uCAoMxD,CAAA;AAED,eAAe,YAAY,CAAA"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../src/site/renderer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,QAAQ,EAOd,MAAM,kBAAkB,CAAA;AAoHzB,eAAO,MAAM,YAAY,GAAI,UAAU;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,uCAmRxD,CAAA;AAED,eAAe,YAAY,CAAA"}

package/dist/site/renderer.js

@@ -1,38 +1,58 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLiveNodeOverrides, useRegistry, useScene, } from '@pascal-app/core';
+import { terrainFieldOf, useLiveNodeOverrides, useLiveTerrain, useRegistry, useScene, } from '@pascal-app/core';
 import { backdropGradient, deepSkyColor, getSceneTheme, horizonHazeColor, NodeRenderer, unionPolygons, useNodeEvents, useViewer, } from '@pascal-app/viewer';
 import { useEffect, useMemo, useRef } from 'react';
-import { BufferGeometry, Float32BufferAttribute, Path, Shape, ShapeGeometry, } from 'three';
+import { BufferAttribute, BufferGeometry, Path, Shape, ShapeGeometry } from 'three';
 import { cameraPosition, color, float, mix, positionWorld, smoothstep, vec2 } from 'three/tsl';
 import { MeshLambertNodeMaterial } from 'three/webgpu';
 import { getRecessedSlabGroundHoles } from './recessed-slab-ground-holes';
+import { buildDrapedPolyline, terrainGridKey, updateDrapedHeights, } from './terrain-drape';
+import { HORIZON_PLANE_Y, terrainFootprint } from './terrain-geometry';
+import { TerrainRenderer } from './terrain-renderer';
 const Y_OFFSET = 0.01;
 // The horizon disc is presentation-only — clicks must fall through to the
 // real site polygon / grid, so its raycast is a no-op.
 const noopRaycast = () => { };
 /**
- * Creates simple line geometry for site boundary
- * Single horizontal line at ground level
+ * The site boundary line, laid on the ground rather than across it.
+ *
+ * On flat ground this is the ring it always was: the polygon's own vertices at
+ * `Y_OFFSET`, closed. On sculpted ground `buildDrapedPolyline` subdivides each
+ * edge at the mesh's creases so the line lies *on* the rendered surface — the lot
+ * line is on screen in every frame, and a flat ring slicing through a hill is the
+ * most conspicuous way sculpted ground reads as broken.
+ *
+ * UVs keep their `(u, 0)` layout, now measured as normalized XZ arc length rather
+ * than vertex index, so a dashed or gradient material spaces evenly along the
+ * perimeter instead of bunching on short edges.
  */
-const createBoundaryLineGeometry = (points) => {
+const createBoundaryLineGeometry = (points, field) => {
     const geometry = new BufferGeometry();
-    if (points.length < 2)
-        return geometry;
-    const positions = [];
-    const uvs = [];
-    // Create a simple line loop at ground level
-    points.forEach(([x, z], index) => {
-        positions.push(x ?? 0, Y_OFFSET, z ?? 0);
-        uvs.push(points.length > 1 ? index / (points.length - 1) : 0, 0);
-    });
-    // Close the loop
-    positions.push(points[0]?.[0] ?? 0, Y_OFFSET, points[0]?.[1] ?? 0);
-    uvs.push(1, 0);
-    geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));
-    geometry.setAttribute('uv', new Float32BufferAttribute(uvs, 2));
-    return geometry;
+    const ring = buildDrapedPolyline({ points, field, lift: Y_OFFSET, closed: true });
+    const uvs = new Float32Array(ring.uvs.length * 2);
+    for (let index = 0; index < ring.uvs.length; index++) {
+        uvs[index * 2] = ring.uvs[index] ?? 0;
+    }
+    // `BufferAttribute`, not `Float32BufferAttribute`: the latter copies its input
+    // into a fresh array, which would leave `ring.positions` a detached CPU copy and
+    // silently break the in-place dab rewrite below. This shares the buffer.
+    geometry.setAttribute('position', new BufferAttribute(ring.positions, 3));
+    geometry.setAttribute('uv', new BufferAttribute(uvs, 2));
+    return { geometry, ring };
 };
+/**
+ * Re-upload a draped ring's positions after an in-place height rewrite.
+ *
+ * No `addUpdateRange`: a dab can move any subset of the ring's vertices (the brush
+ * is a disc, the ring is a loop, and the two intersect in up to four arcs), so a
+ * range would either be the whole buffer or a list. The whole buffer is a few KB.
+ */
+function markPositionsDirty(geometry) {
+    const attribute = geometry.getAttribute('position');
+    attribute.needsUpdate = true;
+    geometry.computeBoundingSphere();
+}
 function polygonsMatch(a, b) {
     return (a.length === b.length &&
         a.every((polygon, polygonIndex) => polygon.length === b[polygonIndex]?.length &&
@@ -66,6 +86,18 @@ export const SiteRenderer = ({ node }) => {
     const maxLightIntensity = useViewer((state) => Math.max(1, ...getSceneTheme(state.sceneTheme).lights.map((light) => light.intensity)));
     const livePolygon = useLiveNodeOverrides((state) => state.overrides.get(node.id)?.polygon ?? null);
     const polygonPoints = livePolygon?.points ?? node.polygon?.points;
+    // Persisted terrain only. A stroke is applied imperatively further down, for the
+    // same reason `TerrainRenderer` does it: a dab must not re-render this subtree.
+    const persistedField = useMemo(() => terrainFieldOf({ id: node.id, terrain: node.terrain }), [node.id, node.terrain]);
+    // The terrain *grid* — mounting, resizing, or re-origining it. `hasTerrain`
+    // catches the first dab on a site that had no terrain at all, which is the one
+    // case where a stroke legitimately changes the grid and everything keyed on it
+    // (the horizon punch, the boundary subdivision) has to rebuild.
+    const hasTerrain = useLiveTerrain((state) => state.strokes.has(node.id));
+    const terrainGrid = hasTerrain
+        ? (useLiveTerrain.getState().fieldOf(node.id) ?? persistedField)
+        : persistedField;
+    const terrainKey = terrainGridKey(terrainGrid);
     // Centroid + radius of the lot polygon, for the presentation fade below.
     const fadeBounds = useMemo(() => {
         if (!polygonPoints || polygonPoints.length < 3)
@@ -158,6 +190,10 @@ export const SiteRenderer = ({ node }) => {
         addSlabHoles(shape, slabPolygons);
         return shape;
     }, [polygonPoints, slabPolygons]);
+    // The terrain footprint is punched out alongside the recessed slabs, and for the
+    // same reason: the disc must not cap ground that is modelled below it.
+    //
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `terrainKey` is the grid signature the footprint is a function of; depending on the field itself would rebuild an 800 m disc every dab.
     const horizonGeometry = useMemo(() => {
         if (!fadeBounds)
             return null;
@@ -170,17 +206,65 @@ export const SiteRenderer = ({ node }) => {
             shape.lineTo(Math.cos(angle) * radius, Math.sin(angle) * radius);
         }
         shape.closePath();
-        addSlabHoles(shape, slabPolygons, fadeBounds.cx, fadeBounds.cz);
+        const holes = terrainGrid ? [...slabPolygons, terrainFootprint(terrainGrid)] : slabPolygons;
+        addSlabHoles(shape, holes, fadeBounds.cx, fadeBounds.cz);
         return new ShapeGeometry(shape);
-    }, [fadeBounds, slabPolygons]);
+    }, [fadeBounds, slabPolygons, terrainKey]);
     useEffect(() => () => horizonGeometry?.dispose(), [horizonGeometry]);
-    // Create boundary line geometry
-    const lineGeometry = useMemo(() => {
+    // Boundary line geometry, subdivided against the terrain grid when there is one.
+    //
+    // Keyed on `terrainKey`, not on the field: the crease set depends on the grid
+    // (origin/spacing/extent) and not on the heights, so a sculpt stroke — which
+    // produces a new field object every dab — must not rebuild this. Heights are
+    // rewritten in place by the subscription below.
+    //
+    // biome-ignore lint/correctness/useExhaustiveDependencies: keyed on the grid, not the field — see above.
+    const boundary = useMemo(() => {
         if (!polygonPoints || polygonPoints.length < 2)
             return null;
-        return createBoundaryLineGeometry(polygonPoints);
-    }, [polygonPoints]);
-    useEffect(() => () => lineGeometry?.dispose(), [lineGeometry]);
+        // The live field, not the persisted one: mounting mid-stroke (the very first
+        // dab on a terrain-free site remounts this subtree) must drape against the
+        // ground actually on screen.
+        const field = useLiveTerrain.getState().fieldOf(node.id) ?? persistedField;
+        return createBoundaryLineGeometry(polygonPoints, field);
+    }, [polygonPoints, terrainKey, node.id]);
+    useEffect(() => () => boundary?.geometry.dispose(), [boundary]);
+    const lineGeometry = boundary?.geometry ?? null;
+    // Per-dab height rewrite, imperative for the same reason `TerrainRenderer`'s
+    // upload is: a stroke pushes dozens of patches a second, and routing each through
+    // a React render would rebuild the ring's buffers at pointer rate. The XZ of every
+    // vertex is a function of the grid alone, so a dab only ever moves Y.
+    //
+    // A ref, not the memo value in a dependency, so the subscription outlives a
+    // polygon edit without resubscribing.
+    const boundaryRef = useRef(null);
+    boundaryRef.current = boundary;
+    useEffect(() => {
+        let lastPatch = useLiveTerrain.getState().strokeOf(node.id)?.lastPatch ?? null;
+        return useLiveTerrain.subscribe((state) => {
+            const current = boundaryRef.current;
+            if (!current)
+                return;
+            const stroke = state.strokes.get(node.id);
+            if (!stroke) {
+                // The stroke ended. Its heights are now the node's, and the commit
+                // re-rendered this subtree with them — but a *cancelled* stroke (Escape)
+                // commits nothing, so the ring has to be put back explicitly.
+                if (lastPatch) {
+                    lastPatch = null;
+                    const field = terrainFieldOf({ id: node.id, terrain: node.terrain });
+                    updateDrapedHeights(current.ring, field, Y_OFFSET);
+                    markPositionsDirty(current.geometry);
+                }
+                return;
+            }
+            if (!stroke.lastPatch || stroke.lastPatch === lastPatch)
+                return;
+            lastPatch = stroke.lastPatch;
+            updateDrapedHeights(current.ring, stroke.field, Y_OFFSET);
+            markPositionsDirty(current.geometry);
+        });
+    }, [node.id, node.terrain]);
     const groundGeometry = useMemo(() => {
         if (!groundShape)
             return null;
@@ -188,9 +272,15 @@ export const SiteRenderer = ({ node }) => {
     }, [groundShape]);
     useEffect(() => () => groundGeometry?.dispose(), [groundGeometry]);
     const handlers = useNodeEvents(node, 'site');
+    // Terrain replaces the flat ground fill rather than sitting on top of it: two
+    // coplanar ground surfaces z-fight, and the flat one would poke through any
+    // excavation. `hasTerrain` (above) is subscribed at the site level rather than
+    // inside TerrainRenderer so a stroke that starts on a site with no persisted
+    // terrain still mounts the mesh.
+    const showTerrain = terrainGrid !== null;
     if (!(node && lineGeometry)) {
         return null;
     }
-    return (_jsxs("group", { ref: ref, ...handlers, children: [(node.children ?? []).map((childId) => (_jsx(NodeRenderer, { nodeId: childId }, childId))), groundGeometry && (_jsx("mesh", { geometry: groundGeometry, material: groundMaterial, position: [0, -0.05, 0], receiveShadow: true, rotation: [-Math.PI / 2, 0, 0] })), horizonGeometry && horizonMaterial && fadeBounds && (_jsx("mesh", { geometry: horizonGeometry, material: horizonMaterial, position: [fadeBounds.cx, -0.07, fadeBounds.cz], raycast: noopRaycast, receiveShadow: true, rotation: [-Math.PI / 2, 0, 0] })), _jsx("line", { frustumCulled: false, geometry: lineGeometry, renderOrder: 9, children: _jsx("lineBasicMaterial", { color: "#f59e0b", linewidth: 2, opacity: 0.6, transparent: true }) })] }));
+    return (_jsxs("group", { ref: ref, ...handlers, children: [(node.children ?? []).map((childId) => (_jsx(NodeRenderer, { nodeId: childId }, childId))), showTerrain && _jsx(TerrainRenderer, { material: groundMaterial, site: node }), groundGeometry && !showTerrain && (_jsx("mesh", { geometry: groundGeometry, material: groundMaterial, position: [0, -0.05, 0], receiveShadow: true, rotation: [-Math.PI / 2, 0, 0] })), horizonGeometry && horizonMaterial && fadeBounds && (_jsx("mesh", { geometry: horizonGeometry, material: horizonMaterial, position: [fadeBounds.cx, HORIZON_PLANE_Y, fadeBounds.cz], raycast: noopRaycast, receiveShadow: true, rotation: [-Math.PI / 2, 0, 0], userData: { pascalExport: 'strip' } })), _jsx("line", { frustumCulled: false, geometry: lineGeometry, renderOrder: 9, children: _jsx("lineBasicMaterial", { color: "#f59e0b", linewidth: 2, opacity: 0.6, transparent: true }) })] }));
 };
 export default SiteRenderer;

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

@@ -0,0 +1,91 @@
+/**
+ * Laying a polyline *on* the terrain surface, exactly.
+ *
+ * The site boundary is the first consumer: a ring of four flat vertices at
+ * `y = 0.01` slices straight through any hill it crosses and floats over any
+ * excavation, which is the single most obvious way sculpted ground looks broken —
+ * the lot line is the one element always on screen.
+ *
+ * The approach is exactness rather than density. The rendered surface is
+ * piecewise-**planar**: `buildTerrainMesh` emits two triangles per cell, so the
+ * only places it creases are the grid lines and each cell's diagonal. Subdivide a
+ * segment at exactly those crossings and every resulting sub-segment lies inside
+ * one triangle, where the surface is a plane and a straight line on it is on it
+ * everywhere. Uniform oversampling can only approach that, and needs an arbitrary
+ * density to argue about.
+ *
+ * In field index space (`u = (x - originX) / spacing`, `v = (z - originZ) /
+ * spacing`) the three crease families are just `u ∈ ℤ`, `v ∈ ℤ`, and `u + v ∈ ℤ` —
+ * the last being the diagonals, since a cell's diagonal runs from `(c+1, r)` to
+ * `(c, r+1)`. All three are affine in the segment parameter, so each crossing is
+ * one division.
+ *
+ * Heights come from `surfaceHeightAt`, the explicit rendered-surface alias for
+ * the shared `heightAt` triangle-plane authority.
+ *
+ * Nothing here touches Three.js: it is array math over a field, so the guarantee
+ * that a sub-segment lies inside one triangle is asserted in unit tests rather
+ * than eyeballed on a canvas.
+ */
+import { type TerrainField } from '@pascal-app/core';
+/** A draped polyline: xyz per vertex, plus normalized arc length per vertex. */
+export type DrapedPolyline = {
+    /** xyz per vertex, length `count * 3`. */
+    positions: Float32Array;
+    /** Normalized distance along the line per vertex, length `count`. */
+    uvs: Float32Array;
+};
+/**
+ * Parameters in `(0, 1)` where the segment crosses a crease of the rendered
+ * surface, sorted and deduplicated.
+ *
+ * Exported for tests: the crease convention is the load-bearing part, and
+ * asserting it on the parameter list is far sharper than inferring it from
+ * vertex positions.
+ */
+export declare function creaseCrossings(field: TerrainField, ax: number, az: number, bx: number, bz: number): number[];
+/**
+ * Build a draped polyline through `points`.
+ *
+ * `field` of `null` means flat ground at the datum: the result is the input
+ * points at `y = lift`, no subdivision. Keeping that case *here* rather than at
+ * every call site is what lets a consumer hold one geometry and one code path
+ * whether or not the site has terrain — and it means a scene that never touched
+ * terrain builds byte-identical buffers to the ones it built before draping
+ * existed.
+ *
+ * `closed` repeats the first point at the end, so a `LineStrip` closes the ring.
+ */
+export declare function buildDrapedPolyline({ points, field, lift, closed, }: {
+    points: ReadonlyArray<readonly [number, number]>;
+    field: TerrainField | null;
+    lift: number;
+    closed: boolean;
+}): DrapedPolyline;
+/**
+ * Rewrite only the heights of an existing draped polyline, in place.
+ *
+ * This is the sculpt-stroke path. The crease set is a function of the field's
+ * *grid* — origin, spacing, sample counts — and not of its heights, so every dab
+ * of a stroke leaves the XZ of every vertex exactly where it was. Rebuilding the
+ * ring per dab would reallocate two buffers and a `BufferGeometry` at pointer
+ * rate for a result that differs only in Y.
+ *
+ * Reads each vertex's own XZ back out of the buffer rather than taking the source
+ * polygon again: there is then no second copy of the subdivision to keep in step.
+ *
+ * Arc lengths are deliberately *not* refreshed — see `writeArcLengths`.
+ */
+export declare function updateDrapedHeights(ring: DrapedPolyline, field: TerrainField | null, lift: number): void;
+/**
+ * Everything about a field that changes the crease set, and nothing that doesn't.
+ *
+ * A React consumer needs to rebuild a draped ring when the *grid* moves and only
+ * rewrite heights when the *heights* move. Keying a memo on the field object would
+ * rebuild every dab (each `applyHeightPatch` returns a new field); keying it on
+ * this rebuilds only when a resize or re-origin actually invalidates the
+ * subdivision, which in practice means import. `null` for no terrain, so the
+ * flat-ground ring is one more value in the same key space.
+ */
+export declare function terrainGridKey(field: TerrainField | null): string | null;
+//# sourceMappingURL=terrain-drape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-drape.d.ts","sourceRoot":"","sources":["../../src/site/terrain-drape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAErE,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG;IAC3B,0CAA0C;IAC1C,SAAS,EAAE,YAAY,CAAA;IACvB,qEAAqE;IACrE,GAAG,EAAE,YAAY,CAAA;CAClB,CAAA;AAcD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,MAAM,EAAE,CAuBV;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,KAAK,EACL,IAAI,EACJ,MAAM,GACP,EAAE;IACD,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAChD,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,cAAc,CA+BjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,YAAY,GAAG,IAAI,EAC1B,IAAI,EAAE,MAAM,GACX,IAAI,CAEN;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAGxE"}

package/dist/site/terrain-drape.js

@@ -0,0 +1,205 @@
+/**
+ * Laying a polyline *on* the terrain surface, exactly.
+ *
+ * The site boundary is the first consumer: a ring of four flat vertices at
+ * `y = 0.01` slices straight through any hill it crosses and floats over any
+ * excavation, which is the single most obvious way sculpted ground looks broken —
+ * the lot line is the one element always on screen.
+ *
+ * The approach is exactness rather than density. The rendered surface is
+ * piecewise-**planar**: `buildTerrainMesh` emits two triangles per cell, so the
+ * only places it creases are the grid lines and each cell's diagonal. Subdivide a
+ * segment at exactly those crossings and every resulting sub-segment lies inside
+ * one triangle, where the surface is a plane and a straight line on it is on it
+ * everywhere. Uniform oversampling can only approach that, and needs an arbitrary
+ * density to argue about.
+ *
+ * In field index space (`u = (x - originX) / spacing`, `v = (z - originZ) /
+ * spacing`) the three crease families are just `u ∈ ℤ`, `v ∈ ℤ`, and `u + v ∈ ℤ` —
+ * the last being the diagonals, since a cell's diagonal runs from `(c+1, r)` to
+ * `(c, r+1)`. All three are affine in the segment parameter, so each crossing is
+ * one division.
+ *
+ * Heights come from `surfaceHeightAt`, the explicit rendered-surface alias for
+ * the shared `heightAt` triangle-plane authority.
+ *
+ * Nothing here touches Three.js: it is array math over a field, so the guarantee
+ * that a sub-segment lies inside one triangle is asserted in unit tests rather
+ * than eyeballed on a canvas.
+ */
+import { surfaceHeightAt } from '@pascal-app/core';
+/**
+ * Crossings per segment, as a backstop only.
+ *
+ * A real segment produces at most ~3 × the field's sample count along it — a few
+ * hundred at 257². The cap exists so a caller that passes a segment spanning a
+ * degenerate field (tiny `spacing`, huge extent) cannot allocate unboundedly.
+ */
+const MAX_CROSSINGS_PER_SEGMENT = 4096;
+/** Two crossings closer than this (in segment parameter) are the same vertex. */
+const PARAM_EPSILON = 1e-9;
+/**
+ * Parameters in `(0, 1)` where the segment crosses a crease of the rendered
+ * surface, sorted and deduplicated.
+ *
+ * Exported for tests: the crease convention is the load-bearing part, and
+ * asserting it on the parameter list is far sharper than inferring it from
+ * vertex positions.
+ */
+export function creaseCrossings(field, ax, az, bx, bz) {
+    const u0 = (ax - field.origin[0]) / field.spacing;
+    const v0 = (az - field.origin[1]) / field.spacing;
+    const u1 = (bx - field.origin[0]) / field.spacing;
+    const v1 = (bz - field.origin[1]) / field.spacing;
+    const crossings = [];
+    // Families are clamped to the index range the surface actually creases over.
+    // Outside the field the surface is the border cell's plane extruded outward, so
+    // crossings out there would add vertices to a stretch that is already flat —
+    // harmless geometrically, but an edge far from a fine grid would emit thousands.
+    addFamily(crossings, u0, u1, 0, field.cols - 1);
+    addFamily(crossings, v0, v1, 0, field.rows - 1);
+    addFamily(crossings, u0 + v0, u1 + v1, 0, field.cols - 1 + (field.rows - 1));
+    crossings.sort((a, b) => a - b);
+    const unique = [];
+    for (const t of crossings) {
+        const previous = unique.at(-1);
+        if (previous !== undefined && t - previous <= PARAM_EPSILON)
+            continue;
+        unique.push(t);
+    }
+    return unique;
+}
+/**
+ * Push the parameters where an affine coordinate `from → to` passes an integer in
+ * `[loBound, hiBound]`.
+ */
+function addFamily(out, from, to, loBound, hiBound) {
+    const delta = to - from;
+    // Parallel to this family: no crossing, whether or not it lies *on* a crease.
+    // A segment running along a grid line is already inside the planes on both
+    // sides, so it needs no extra vertex.
+    if (Math.abs(delta) < 1e-12)
+        return;
+    const lo = Math.max(loBound, Math.ceil(Math.min(from, to)));
+    const hi = Math.min(hiBound, Math.floor(Math.max(from, to)));
+    let emitted = 0;
+    for (let k = lo; k <= hi; k++) {
+        const t = (k - from) / delta;
+        if (t <= PARAM_EPSILON || t >= 1 - PARAM_EPSILON)
+            continue;
+        out.push(t);
+        emitted += 1;
+        if (emitted >= MAX_CROSSINGS_PER_SEGMENT)
+            return;
+    }
+}
+/**
+ * Build a draped polyline through `points`.
+ *
+ * `field` of `null` means flat ground at the datum: the result is the input
+ * points at `y = lift`, no subdivision. Keeping that case *here* rather than at
+ * every call site is what lets a consumer hold one geometry and one code path
+ * whether or not the site has terrain — and it means a scene that never touched
+ * terrain builds byte-identical buffers to the ones it built before draping
+ * existed.
+ *
+ * `closed` repeats the first point at the end, so a `LineStrip` closes the ring.
+ */
+export function buildDrapedPolyline({ points, field, lift, closed, }) {
+    const xz = [];
+    const segments = closed ? points.length : points.length - 1;
+    for (let index = 0; index < segments; index++) {
+        const from = points[index];
+        const to = points[(index + 1) % points.length];
+        if (!(from && to))
+            continue;
+        const [ax, az] = from;
+        const [bx, bz] = to;
+        xz.push([ax, az]);
+        if (!field)
+            continue;
+        for (const t of creaseCrossings(field, ax, az, bx, bz)) {
+            xz.push([ax + (bx - ax) * t, az + (bz - az) * t]);
+        }
+    }
+    // The final vertex: the ring's start again when closed, otherwise the last
+    // point, which the segment loop above never emits.
+    const last = closed ? points[0] : points.at(-1);
+    if (last)
+        xz.push([last[0], last[1]]);
+    const positions = new Float32Array(xz.length * 3);
+    for (let index = 0; index < xz.length; index++) {
+        const [x, z] = xz[index];
+        positions[index * 3] = x;
+        positions[index * 3 + 2] = z;
+    }
+    const ring = { positions, uvs: new Float32Array(xz.length) };
+    writeDrapedHeights(ring, field, lift);
+    writeArcLengths(ring);
+    return ring;
+}
+/**
+ * Rewrite only the heights of an existing draped polyline, in place.
+ *
+ * This is the sculpt-stroke path. The crease set is a function of the field's
+ * *grid* — origin, spacing, sample counts — and not of its heights, so every dab
+ * of a stroke leaves the XZ of every vertex exactly where it was. Rebuilding the
+ * ring per dab would reallocate two buffers and a `BufferGeometry` at pointer
+ * rate for a result that differs only in Y.
+ *
+ * Reads each vertex's own XZ back out of the buffer rather than taking the source
+ * polygon again: there is then no second copy of the subdivision to keep in step.
+ *
+ * Arc lengths are deliberately *not* refreshed — see `writeArcLengths`.
+ */
+export function updateDrapedHeights(ring, field, lift) {
+    writeDrapedHeights(ring, field, lift);
+}
+function writeDrapedHeights(ring, field, lift) {
+    const count = ring.uvs.length;
+    for (let index = 0; index < count; index++) {
+        const x = ring.positions[index * 3] ?? 0;
+        const z = ring.positions[index * 3 + 2] ?? 0;
+        ring.positions[index * 3 + 1] = field ? surfaceHeightAt(field, x, z) + lift : lift;
+    }
+}
+/**
+ * Normalized cumulative distance along the line, measured in **XZ**.
+ *
+ * Horizontal, not 3D: the value has to be stable while the ground moves under a
+ * stroke, and a 3D arc length is not — it would stretch as a hill rises, sliding
+ * any dash pattern along the ring dab by dab. XZ length is what a plan-view
+ * reading of the lot line uses anyway, so the 2D and 3D views agree on it.
+ */
+function writeArcLengths(ring) {
+    const count = ring.uvs.length;
+    if (count === 0)
+        return;
+    let total = 0;
+    for (let index = 1; index < count; index++) {
+        const dx = (ring.positions[index * 3] ?? 0) - (ring.positions[(index - 1) * 3] ?? 0);
+        const dz = (ring.positions[index * 3 + 2] ?? 0) - (ring.positions[(index - 1) * 3 + 2] ?? 0);
+        total += Math.hypot(dx, dz);
+        ring.uvs[index] = total;
+    }
+    if (total <= 0)
+        return;
+    for (let index = 1; index < count; index++) {
+        ring.uvs[index] = (ring.uvs[index] ?? 0) / total;
+    }
+}
+/**
+ * Everything about a field that changes the crease set, and nothing that doesn't.
+ *
+ * A React consumer needs to rebuild a draped ring when the *grid* moves and only
+ * rewrite heights when the *heights* move. Keying a memo on the field object would
+ * rebuild every dab (each `applyHeightPatch` returns a new field); keying it on
+ * this rebuilds only when a resize or re-origin actually invalidates the
+ * subdivision, which in practice means import. `null` for no terrain, so the
+ * flat-ground ring is one more value in the same key space.
+ */
+export function terrainGridKey(field) {
+    if (!field)
+        return null;
+    return `${field.origin[0]}:${field.origin[1]}:${field.spacing}:${field.cols}:${field.rows}`;
+}