@pascal-app/core 1.0.1 → 1.0.4

package/dist/lib/structure-reconcile.d.ts

@@ -0,0 +1,15 @@
+import { type NodePatch, type SceneNodes, type StructureEvent } from './structure-kernel.js';
+export type StructureIdFactory = (kind: 'zone' | 'ceiling' | 'slab' | 'separator') => string;
+export type SceneStructureInput = {
+    nodes: SceneNodes;
+    levelIds?: string[];
+    mintId: StructureIdFactory;
+    previousNodes?: SceneNodes;
+};
+export type SceneStructureResult = {
+    nodes: SceneNodes;
+    patches: NodePatch[];
+    events: StructureEvent[];
+};
+export declare function reconcileSceneStructure({ nodes, levelIds, mintId, previousNodes, }: SceneStructureInput): SceneStructureResult;
+//# sourceMappingURL=structure-reconcile.d.ts.map

package/dist/lib/structure-reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-reconcile.d.ts","sourceRoot":"","sources":["../../src/lib/structure-reconcile.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAA;AAE3B,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,KAAK,MAAM,CAAA;AAC5F,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,UAAU,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,MAAM,EAAE,kBAAkB,CAAA;IAC1B,aAAa,CAAC,EAAE,UAAU,CAAA;CAC3B,CAAA;AACD,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,UAAU,CAAA;IACjB,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,MAAM,EAAE,cAAc,EAAE,CAAA;CACzB,CAAA;AAyED,wBAAgB,uBAAuB,CAAC,EACtC,KAAK,EACL,QAAQ,EACR,MAAM,EACN,aAAa,GACd,EAAE,mBAAmB,GAAG,oBAAoB,CA+K5C"}

package/dist/lib/structure-reconcile.js

@@ -0,0 +1,218 @@
+import { floorFootprintSupportClass } from './floor-foundation-datum.js';
+import { createFloorOpeningIndex } from './floor-opening-intent.js';
+import { extractRooms, pointToTuple, sampleWallPointsForRoomDetection, WALL_JUNCTION_TOLERANCE, } from './room-graph.js';
+import { RoomTopologyIndex } from './room-topology-index.js';
+import { reconcileLevelStructure, } from './structure-kernel.js';
+function levelChildren(nodes, levelId) {
+    return Object.values(nodes)
+        .filter((node) => node.parentId === levelId)
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+function applyPatch(nodes, patch) {
+    if (patch.op === 'delete')
+        delete nodes[patch.id];
+    else if (patch.op === 'create')
+        nodes[patch.node.id] = patch.node;
+    else {
+        const node = { ...nodes[patch.id], ...patch.data };
+        for (const [key, value] of Object.entries(patch.data))
+            if (value === undefined)
+                delete node[key];
+        nodes[patch.id] = node;
+    }
+}
+function affectedWalls(levelId, nodes, previousNodes, children, previousChildren) {
+    const changed = new Set([...children, ...previousChildren]
+        .filter((node) => node.type === 'wall' &&
+        JSON.stringify(nodes[node.id]) !== JSON.stringify(previousNodes[node.id]))
+        .map((node) => node.id));
+    if (!changed.size)
+        return;
+    const index = new RoomTopologyIndex({
+        detectRooms: extractRooms,
+        sampleWall: (wall) => sampleWallPointsForRoomDetection(wall).map(pointToTuple),
+        junctionTolerance: WALL_JUNCTION_TOLERANCE,
+        includeSeparators: false,
+    });
+    return new Set(index.applyWallDelta(levelId, changed, previousNodes, nodes).examinedWallIds);
+}
+function supportInputsChanged(before, after) {
+    for (const id of new Set([...Object.keys(before), ...Object.keys(after)])) {
+        const old = before[id], next = after[id];
+        if (old === next)
+            continue;
+        if (old?.type === 'slab' || next?.type === 'slab') {
+            if (old?.type !== 'slab' || next?.type !== 'slab')
+                return true;
+            if (old.plateRole === 'base' || next.plateRole === 'base') {
+                if (old.plateRole !== next.plateRole)
+                    return true;
+                if (old.parentId !== next.parentId ||
+                    JSON.stringify([old.polygon, old.holes, old.zoneIds]) !==
+                        JSON.stringify([next.polygon, next.holes, next.zoneIds]))
+                    return true;
+            }
+        }
+        if ((old?.type === 'zone' && old.spaceRole === 'room') !==
+            (next?.type === 'zone' && next.spaceRole === 'room'))
+            return true;
+        if (old?.type === 'level' && next?.type === 'level')
+            if (old.level !== next.level || old.parentId !== next.parentId)
+                return true;
+    }
+    return false;
+}
+export function reconcileSceneStructure({ nodes, levelIds, mintId, previousNodes, }) {
+    const draft = { ...nodes };
+    const events = [];
+    const openingIndex = createFloorOpeningIndex(nodes);
+    // Reconcile covering slabs before the ceilings on the level below them.
+    const levels = [
+        ...new Set(levelIds ??
+            Object.values(nodes)
+                .filter((node) => node.type === 'level')
+                .map((node) => node.id)),
+    ].sort((a, b) => (nodes[b]?.type === 'level' ? nodes[b].level : 0) -
+        (nodes[a]?.type === 'level' ? nodes[a].level : 0) || (a < b ? -1 : a > b ? 1 : 0));
+    const reconcileLevel = (levelId) => {
+        if (draft[levelId]?.type !== 'level')
+            return;
+        const children = levelChildren(draft, levelId);
+        const previousChildren = previousNodes ? levelChildren(previousNodes, levelId) : [];
+        for (const surface of previousChildren) {
+            if ((surface.type !== 'ceiling' && surface.type !== 'slab') ||
+                surface.boundary !== 'auto' ||
+                draft[surface.id])
+                continue;
+            const ids = surface.type === 'ceiling' ? [surface.zoneId] : (surface.zoneIds ?? []);
+            for (const id of ids) {
+                const zone = id ? draft[id] : undefined;
+                if (zone?.type === 'zone')
+                    draft[zone.id] = {
+                        ...zone,
+                        [surface.type === 'ceiling' ? 'hasCeiling' : 'hasFloor']: false,
+                    };
+            }
+        }
+        const wallIds = previousNodes
+            ? affectedWalls(levelId, nodes, previousNodes, children, previousChildren)
+            : undefined;
+        const structure = reconcileLevelStructure({
+            levelId,
+            nodes: draft,
+            mintId,
+            previousNodes,
+            openingIndex,
+        });
+        for (const patch of structure.patches) {
+            // Preserve the indexed edit's wall scope: remote legacy walls must not
+            // become a full-level rebuild merely because their sides were unclassified.
+            if (patch.op === 'update' &&
+                wallIds &&
+                draft[patch.id]?.type === 'wall' &&
+                !wallIds.has(patch.id))
+                continue;
+            applyPatch(draft, patch);
+        }
+        events.push(...structure.events);
+    };
+    for (const levelId of levels)
+        reconcileLevel(levelId);
+    const flipped = new Set();
+    if (supportInputsChanged(nodes, draft)) {
+        const supportClasses = new Map(Object.values(nodes).flatMap((node) => node.type === 'slab' && node.plateRole === 'base'
+            ? [[node.id, floorFootprintSupportClass(nodes, node)]]
+            : []));
+        for (const node of Object.values(draft))
+            if (node.type === 'slab' &&
+                node.plateRole === 'base' &&
+                floorFootprintSupportClass(draft, node) !==
+                    (supportClasses.get(node.id) ?? 'ground-bearing'))
+                flipped.add(node.parentId);
+    }
+    if (flipped.size) {
+        for (const levelId of [...flipped]) {
+            const index = levels.indexOf(levelId);
+            if (index >= 0 && index + 1 < levels.length)
+                flipped.add(levels[index + 1]);
+        }
+        for (const levelId of levels)
+            if (flipped.has(levelId))
+                reconcileLevel(levelId);
+    }
+    const legacyCutsBySurface = new Map();
+    for (const node of Object.values(draft)) {
+        if (node.type !== 'floor-opening')
+            continue;
+        for (const [surfaceId, cuts] of Object.entries({
+            ...node.legacyPlateCuts,
+            ...node.legacyCeilingCuts,
+        }))
+            for (const hole of cuts) {
+                const byPolygon = legacyCutsBySurface.get(surfaceId) ?? new Map();
+                const key = JSON.stringify(hole);
+                const existing = byPolygon.get(key);
+                if (!existing || node.id < existing.metadata.openingId)
+                    byPolygon.set(key, { hole, metadata: { source: 'floor-opening', openingId: node.id } });
+                legacyCutsBySurface.set(surfaceId, byPolygon);
+            }
+    }
+    const levelSet = new Set(levels);
+    for (const surface of Object.values(draft)) {
+        if ((surface.type !== 'slab' && surface.type !== 'ceiling') ||
+            surface.boundary === 'auto' ||
+            !levelSet.has(surface.parentId ?? ''))
+            continue;
+        const desired = [...(legacyCutsBySurface.get(surface.id)?.values() ?? [])];
+        const retained = (surface.holes ?? []).flatMap((hole, index) => {
+            const metadata = surface.holeMetadata?.[index];
+            if (metadata?.source !== 'floor-opening')
+                return [{ hole, metadata: metadata ?? { source: 'manual' } }];
+            const opening = metadata.openingId ? draft[metadata.openingId] : undefined;
+            return opening?.type === 'floor-opening' &&
+                !opening.legacyPlateCuts?.[surface.id] &&
+                !opening.legacyCeilingCuts?.[surface.id]
+                ? [{ hole, metadata }]
+                : [];
+        });
+        const holes = [...retained, ...desired];
+        if (JSON.stringify([surface.holes ?? [], surface.holeMetadata ?? []]) !==
+            JSON.stringify([holes.map((entry) => entry.hole), holes.map((entry) => entry.metadata)]))
+            draft[surface.id] = {
+                ...surface,
+                holes: holes.map((entry) => entry.hole),
+                holeMetadata: holes.map((entry) => entry.metadata),
+            };
+    }
+    const patches = [];
+    for (const id of [...new Set([...Object.keys(nodes), ...Object.keys(draft)])].sort()) {
+        const before = nodes[id];
+        const after = draft[id];
+        if (before === after)
+            continue;
+        if (!after) {
+            patches.push({ op: 'delete', id: id });
+            continue;
+        }
+        if (!before) {
+            patches.push({ op: 'create', node: after });
+            continue;
+        }
+        const data = {};
+        for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+            const value = after[key];
+            if (JSON.stringify(before[key]) !==
+                JSON.stringify(value))
+                data[key] = value;
+        }
+        if (Object.keys(data).length)
+            patches.push({ op: 'update', id: after.id, data: data });
+        else
+            draft[id] = before;
+    }
+    return {
+        nodes: patches.length ? draft : nodes,
+        patches,
+        events: events.filter((event, index) => events.findIndex((other) => JSON.stringify(other) === JSON.stringify(event)) === index),
+    };
+}

package/dist/lib/terrain-contours.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Terrain contour lines (the site plan's and the 3D view's), from the site's heightfield.
+ *
+ * Marching squares over the field's samples at a chosen interval: every
+ * cell whose four corner heights straddle a level gets one or two segments
+ * (the saddle case split by the centre height), and the segments are
+ * chained into polylines. Only segments whose midpoint lies inside the lot
+ * are kept, so the lines stop at the property line the way a survey's do.
+ * Elevations are the field's (relative to the site datum, metres); the
+ * caller adds the datum for absolute feet when the terrain sample carries
+ * one. Pure.
+ *
+ * Drawn on the site plan at a user-selectable contour interval (6", 12", …).
+ */
+import { type TerrainField } from './terrain-field.js';
+export type Pt = readonly [number, number];
+export type Contour = {
+    /** The level, site metres above the datum. */
+    levelM: number;
+    points: Pt[];
+    /** Every N-th line is an index contour (heavier, labelled). */
+    index: boolean;
+};
+/**
+ * The contours of a field at `intervalM`, clipped to the lot. Every fifth
+ * level (counted from zero) is an index contour.
+ */
+export declare function terrainContours(field: TerrainField, intervalM: number, lot: readonly Pt[]): Contour[];
+//# sourceMappingURL=terrain-contours.d.ts.map

package/dist/lib/terrain-contours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-contours.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-contours.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnE,MAAM,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAc1C,MAAM,MAAM,OAAO,GAAG;IACpB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,EAAE,EAAE,CAAA;IACZ,+DAA+D;IAC/D,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAkJD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,SAAS,EAAE,EAAE,GACjB,OAAO,EAAE,CA0BX"}

package/dist/lib/terrain-contours.js

@@ -0,0 +1,199 @@
+/**
+ * Terrain contour lines (the site plan's and the 3D view's), from the site's heightfield.
+ *
+ * Marching squares over the field's samples at a chosen interval: every
+ * cell whose four corner heights straddle a level gets one or two segments
+ * (the saddle case split by the centre height), and the segments are
+ * chained into polylines. Only segments whose midpoint lies inside the lot
+ * are kept, so the lines stop at the property line the way a survey's do.
+ * Elevations are the field's (relative to the site datum, metres); the
+ * caller adds the datum for absolute feet when the terrain sample carries
+ * one. Pure.
+ *
+ * Drawn on the site plan at a user-selectable contour interval (6", 12", …).
+ */
+import { heightAtSample } from './terrain-field.js';
+/** Even–odd point-in-polygon (the site plan's rule, copied so core owns the module). */
+function pointInPolygon(points, x, y) {
+    let inside = false;
+    for (let i = 0, j = points.length - 1; i < points.length; j = i++) {
+        const a = points[i];
+        const b = points[j];
+        if (a[1] > y !== b[1] > y && x < ((b[0] - a[0]) * (y - a[1])) / (b[1] - a[1] || 1e-12) + a[0])
+            inside = !inside;
+    }
+    return inside;
+}
+/** Interpolate the crossing of `level` between two corners. */
+function cross(ax, az, ah, bx, bz, bh, level) {
+    const t = bh === ah ? 0.5 : (level - ah) / (bh - ah);
+    return [ax + (bx - ax) * t, az + (bz - az) * t];
+}
+/** The segments of one level across the field (marching squares, 16 cases). */
+function levelSegments(field, level, lot) {
+    const out = [];
+    const { cols, rows, spacing } = field;
+    const [ox, oz] = field.origin;
+    for (let row = 0; row + 1 < rows; row++) {
+        for (let col = 0; col + 1 < cols; col++) {
+            // corners: a = (col,row) b = (col+1,row) c = (col+1,row+1) d = (col,row+1)
+            const ha = heightAtSample(field, col, row);
+            const hb = heightAtSample(field, col + 1, row);
+            const hc = heightAtSample(field, col + 1, row + 1);
+            const hd = heightAtSample(field, col, row + 1);
+            const code = (ha >= level ? 8 : 0) |
+                (hb >= level ? 4 : 0) |
+                (hc >= level ? 2 : 0) |
+                (hd >= level ? 1 : 0);
+            if (code === 0 || code === 15)
+                continue;
+            const x0 = ox + col * spacing;
+            const x1 = x0 + spacing;
+            const z0 = oz + row * spacing;
+            const z1 = z0 + spacing;
+            const top = () => cross(x0, z0, ha, x1, z0, hb, level);
+            const right = () => cross(x1, z0, hb, x1, z1, hc, level);
+            const bottom = () => cross(x0, z1, hd, x1, z1, hc, level);
+            const left = () => cross(x0, z0, ha, x0, z1, hd, level);
+            const push = (p, q) => {
+                const mx = (p[0] + q[0]) / 2;
+                const mz = (p[1] + q[1]) / 2;
+                if (lot.length < 3 || pointInPolygon(lot, mx, mz))
+                    out.push([p, q]);
+            };
+            switch (code) {
+                case 1:
+                case 14:
+                    push(left(), bottom());
+                    break;
+                case 2:
+                case 13:
+                    push(bottom(), right());
+                    break;
+                case 3:
+                case 12:
+                    push(left(), right());
+                    break;
+                case 4:
+                case 11:
+                    push(top(), right());
+                    break;
+                case 6:
+                case 9:
+                    push(top(), bottom());
+                    break;
+                case 7:
+                case 8:
+                    push(left(), top());
+                    break;
+                case 5:
+                case 10: {
+                    // the saddle: split by the cell's centre height
+                    const centre = (ha + hb + hc + hd) / 4;
+                    const high = centre >= level;
+                    if ((code === 5) === high) {
+                        push(left(), top());
+                        push(bottom(), right());
+                    }
+                    else {
+                        push(left(), bottom());
+                        push(top(), right());
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+    }
+    return out;
+}
+/** Chain segments end to end into polylines (a tolerance of a centimetre). */
+function chain(segments) {
+    const key = (p) => `${Math.round(p[0] * 100)},${Math.round(p[1] * 100)}`;
+    const unused = new Set();
+    const byEnd = new Map();
+    segments.forEach((s, i) => {
+        unused.add(i);
+        for (const p of s) {
+            const k = key(p);
+            const list = byEnd.get(k) ?? [];
+            list.push(i);
+            byEnd.set(k, list);
+        }
+    });
+    const takeFrom = (p) => {
+        for (const i of byEnd.get(key(p)) ?? []) {
+            if (unused.has(i)) {
+                unused.delete(i);
+                return { seg: segments[i], i };
+            }
+        }
+        return null;
+    };
+    const lines = [];
+    while (unused.size > 0) {
+        const first = unused.values().next().value;
+        unused.delete(first);
+        const seg = segments[first];
+        const line = [seg[0], seg[1]];
+        // grow forward
+        for (;;) {
+            const tail = line[line.length - 1];
+            const next = takeFrom(tail);
+            if (!next)
+                break;
+            const other = key(next.seg[0]) === key(tail) ? next.seg[1] : next.seg[0];
+            line.push(other);
+        }
+        // grow backward
+        for (;;) {
+            const head = line[0];
+            const prev = takeFrom(head);
+            if (!prev)
+                break;
+            const other = key(prev.seg[0]) === key(head) ? prev.seg[1] : prev.seg[0];
+            line.unshift(other);
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/**
+ * The contours of a field at `intervalM`, clipped to the lot. Every fifth
+ * level (counted from zero) is an index contour.
+ */
+export function terrainContours(field, intervalM, lot) {
+    if (!(intervalM > 0))
+        return [];
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    for (let row = 0; row < field.rows; row++) {
+        for (let col = 0; col < field.cols; col++) {
+            const h = heightAtSample(field, col, row);
+            if (h < lo)
+                lo = h;
+            if (h > hi)
+                hi = h;
+        }
+    }
+    if (!Number.isFinite(lo) || hi - lo < 1e-6)
+        return [];
+    const first = Math.ceil(lo / intervalM);
+    const last = Math.floor(hi / intervalM);
+    if (last - first > 400)
+        return []; // an absurd interval for the relief — refuse rather than draw a blot
+    const out = [];
+    for (let k = first; k <= last; k++) {
+        const level = k * intervalM;
+        const segs = levelSegments(field, level, lot);
+        if (segs.length === 0)
+            continue;
+        for (const points of chain(segs)) {
+            if (points.length < 2)
+                continue;
+            out.push({ levelM: level, points, index: k % 5 === 0 });
+        }
+    }
+    return out;
+}

package/dist/lib/terrain-source-persisted.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Scene → `TerrainField`, cached.
+ *
+ * Every consumer that needs the ground — the mesh builder, the raycast, the
+ * placement predicate, the collider, the 2D view — starts here. It exists to
+ * solve one problem: the scene stores terrain as base64 (`site.terrain`), and
+ * decoding that per frame, or per pointer-move, would be absurd.
+ *
+ * The cache is a `WeakMap` keyed on the **`TerrainData` object identity**, which
+ * is a correct version key because the scene store is immutable-by-convention:
+ * `updateNode` produces a new node object with a new `terrain` object, so a
+ * changed terrain necessarily misses the cache and a stale entry is unreachable.
+ * No invalidation call, no version counter, nothing to forget to bump.
+ *
+ * `commitTerrainField` closes the loop: it encodes a field *and* primes the cache
+ * with the field it just encoded. That is what makes a sculpt stroke free — after
+ * the commit, the next read is a cache hit, so a stroke never decodes base64 even
+ * once, let alone per dab.
+ */
+import type { SiteNode } from '../schema/nodes/site.js';
+import type { TerrainData } from '../schema/terrain.js';
+import { createTerrainField, type TerrainField } from './terrain-field.js';
+export declare function persistedTerrainFieldOf(site: Pick<SiteNode, 'terrain'> | null | undefined): TerrainField | null;
+/**
+ * The field a site *would* sculpt into: its existing terrain, or a fresh flat
+ * field sized to `options`.
+ *
+ * Separate from `terrainFieldOf` because the read path wants `null` for "no
+ * terrain" and the write path wants something to write into. Collapsing them
+ * would force every reader to allocate a field it does not need.
+ */
+export declare function terrainFieldForEdit(site: Pick<SiteNode, 'terrain'> | null | undefined, options?: Parameters<typeof createTerrainField>[0]): TerrainField;
+/**
+ * Encode a field for persistence and prime the read cache with it.
+ *
+ * Call this instead of `encodeTerrainField` whenever the result is going into the
+ * scene. The returned data is what to write to `site.terrain`; the cache priming
+ * means the very next `terrainFieldOf` on the updated node returns this exact
+ * field object without decoding.
+ */
+export declare function commitTerrainField(field: TerrainField): TerrainData;
+//# sourceMappingURL=terrain-source-persisted.d.ts.map

package/dist/lib/terrain-source-persisted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-source-persisted.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-source-persisted.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAUvE,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,GACjD,YAAY,GAAG,IAAI,CAcrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACjD,YAAY,CAEd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAInE"}

package/dist/lib/terrain-source-persisted.js

@@ -0,0 +1,68 @@
+/**
+ * Scene → `TerrainField`, cached.
+ *
+ * Every consumer that needs the ground — the mesh builder, the raycast, the
+ * placement predicate, the collider, the 2D view — starts here. It exists to
+ * solve one problem: the scene stores terrain as base64 (`site.terrain`), and
+ * decoding that per frame, or per pointer-move, would be absurd.
+ *
+ * The cache is a `WeakMap` keyed on the **`TerrainData` object identity**, which
+ * is a correct version key because the scene store is immutable-by-convention:
+ * `updateNode` produces a new node object with a new `terrain` object, so a
+ * changed terrain necessarily misses the cache and a stale entry is unreachable.
+ * No invalidation call, no version counter, nothing to forget to bump.
+ *
+ * `commitTerrainField` closes the loop: it encodes a field *and* primes the cache
+ * with the field it just encoded. That is what makes a sculpt stroke free — after
+ * the commit, the next read is a cache hit, so a stroke never decodes base64 even
+ * once, let alone per dab.
+ */
+import { decodeTerrainField, encodeTerrainField } from './terrain-codec.js';
+import { createTerrainField } from './terrain-field.js';
+const fieldCache = new WeakMap();
+/**
+ * Sites whose `terrain` failed to decode. Prevents re-attempting a doomed decode
+ * on every frame — the corrupt-scene path must be cheap, not just survivable.
+ */
+const failedDecodes = new WeakSet();
+export function persistedTerrainFieldOf(site) {
+    const data = site?.terrain;
+    if (!data)
+        return null;
+    const cached = fieldCache.get(data);
+    if (cached)
+        return cached;
+    if (failedDecodes.has(data))
+        return null;
+    const field = decodeTerrainField(data);
+    if (!field) {
+        failedDecodes.add(data);
+        return null;
+    }
+    fieldCache.set(data, field);
+    return field;
+}
+/**
+ * The field a site *would* sculpt into: its existing terrain, or a fresh flat
+ * field sized to `options`.
+ *
+ * Separate from `terrainFieldOf` because the read path wants `null` for "no
+ * terrain" and the write path wants something to write into. Collapsing them
+ * would force every reader to allocate a field it does not need.
+ */
+export function terrainFieldForEdit(site, options) {
+    return persistedTerrainFieldOf(site) ?? createTerrainField(options);
+}
+/**
+ * Encode a field for persistence and prime the read cache with it.
+ *
+ * Call this instead of `encodeTerrainField` whenever the result is going into the
+ * scene. The returned data is what to write to `site.terrain`; the cache priming
+ * means the very next `terrainFieldOf` on the updated node returns this exact
+ * field object without decoding.
+ */
+export function commitTerrainField(field) {
+    const data = encodeTerrainField(field);
+    fieldCache.set(data, field);
+    return data;
+}

package/dist/lib/terrain-source.d.ts

@@ -1,25 +1,6 @@
-/**
- * Scene → `TerrainField`, cached.
- *
- * Every consumer that needs the ground — the mesh builder, the raycast, the
- * placement predicate, the collider, the 2D view — starts here. It exists to
- * solve one problem: the scene stores terrain as base64 (`site.terrain`), and
- * decoding that per frame, or per pointer-move, would be absurd.
- *
- * The cache is a `WeakMap` keyed on the **`TerrainData` object identity**, which
- * is a correct version key because the scene store is immutable-by-convention:
- * `updateNode` produces a new node object with a new `terrain` object, so a
- * changed terrain necessarily misses the cache and a stale entry is unreachable.
- * No invalidation call, no version counter, nothing to forget to bump.
- *
- * `commitTerrainField` closes the loop: it encodes a field *and* primes the cache
- * with the field it just encoded. That is what makes a sculpt stroke free — after
- * the commit, the next read is a cache hit, so a stroke never decodes base64 even
- * once, let alone per dab.
- */
 import type { SiteNode } from '../schema/nodes/site.js';
-import type { TerrainData } from '../schema/terrain.js';
-import { createTerrainField, type TerrainField } from './terrain-field.js';
+import type { TerrainField } from './terrain-field.js';
+export { commitTerrainField, persistedTerrainFieldOf, terrainFieldForEdit, } from './terrain-source-persisted.js';
 /**
  * The terrain field for a site, or `null` when the site has no sculpted terrain.
  *
@@ -39,23 +20,4 @@ import { createTerrainField, type TerrainField } from './terrain-field.js';
 export declare function terrainFieldOf(site: (Pick<SiteNode, 'terrain'> & {
     id?: string;
 }) | null | undefined): TerrainField | null;
-export declare function persistedTerrainFieldOf(site: Pick<SiteNode, 'terrain'> | null | undefined): TerrainField | null;
-/**
- * The field a site *would* sculpt into: its existing terrain, or a fresh flat
- * field sized to `options`.
- *
- * Separate from `terrainFieldOf` because the read path wants `null` for "no
- * terrain" and the write path wants something to write into. Collapsing them
- * would force every reader to allocate a field it does not need.
- */
-export declare function terrainFieldForEdit(site: Pick<SiteNode, 'terrain'> | null | undefined, options?: Parameters<typeof createTerrainField>[0]): TerrainField;
-/**
- * Encode a field for persistence and prime the read cache with it.
- *
- * Call this instead of `encodeTerrainField` whenever the result is going into the
- * scene. The returned data is what to write to `site.terrain`; the cache priming
- * means the very next `terrainFieldOf` on the updated node returns this exact
- * field object without decoding.
- */
-export declare function commitTerrainField(field: TerrainField): TerrainData;
 //# sourceMappingURL=terrain-source.d.ts.map

package/dist/lib/terrain-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terrain-source.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAUvE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACrE,YAAY,GAAG,IAAI,CAMrB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,GACjD,YAAY,GAAG,IAAI,CAcrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,GACjD,YAAY,CAEd;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAInE"}
+{"version":3,"file":"terrain-source.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAEpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,4BAA4B,CAAA;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GACrE,YAAY,GAAG,IAAI,CAMrB"}