@pascal-app/core 0.9.2 → 1.0.0-beta.1

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

@@ -0,0 +1,60 @@
+/**
+ * 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';
+import type { TerrainData } from '../schema/terrain';
+import { createTerrainField, type TerrainField } from './terrain-field';
+/**
+ * The terrain field for a site, or `null` when the site has no sculpted terrain.
+ *
+ * `null` means flat ground at the datum. It is deliberately not "a flat field":
+ * callers use `null` to take their existing flat-ground fast path, which keeps
+ * every scene that has never touched terrain — the overwhelming majority —
+ * running exactly the code it ran before terrain existed. That property is worth
+ * more than the uniformity of always having a field.
+ *
+ * An in-flight sculpt stroke wins over the persisted data. Resolving that *here*
+ * rather than per caller is what makes a stroke consistent: the mesh, the pointer
+ * raycast, the placement predicate, the collider, and the 2D view all see the
+ * same ground mid-drag without any of them knowing a stroke exists. The
+ * alternative — each consumer checking the live store — is how a drag ends up
+ * showing a hill the raycast cannot hit.
+ */
+export declare function terrainFieldOf(site: (Pick<SiteNode, 'terrain'> & {
+    id?: string;
+}) | 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

@@ -0,0 +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,CAkBrB;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.js

@@ -0,0 +1,90 @@
+/**
+ * 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 useLiveTerrain from '../store/use-live-terrain';
+import { decodeTerrainField, encodeTerrainField } from './terrain-codec';
+import { createTerrainField } from './terrain-field';
+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();
+/**
+ * The terrain field for a site, or `null` when the site has no sculpted terrain.
+ *
+ * `null` means flat ground at the datum. It is deliberately not "a flat field":
+ * callers use `null` to take their existing flat-ground fast path, which keeps
+ * every scene that has never touched terrain — the overwhelming majority —
+ * running exactly the code it ran before terrain existed. That property is worth
+ * more than the uniformity of always having a field.
+ *
+ * An in-flight sculpt stroke wins over the persisted data. Resolving that *here*
+ * rather than per caller is what makes a stroke consistent: the mesh, the pointer
+ * raycast, the placement predicate, the collider, and the 2D view all see the
+ * same ground mid-drag without any of them knowing a stroke exists. The
+ * alternative — each consumer checking the live store — is how a drag ends up
+ * showing a hill the raycast cannot hit.
+ */
+export function terrainFieldOf(site) {
+    if (site?.id) {
+        const live = useLiveTerrain.getState().fieldOf(site.id);
+        if (live)
+            return live;
+    }
+    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 terrainFieldOf(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-support.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Terrain as the level base — the third and last place flat ground was assumed.
+ *
+ * `getFloorPlacedElevation` returns a *lift* added to a node's level-local Y, and
+ * two of its `0`-returns mean "supported by the level base". This module is what
+ * those two branches call so that "the level base" can mean the sculpted ground
+ * instead of the plane `y = 0`. The other `0`-returns are `+0` no-ops for
+ * wall/ceiling-attached items, non-`level` parents, and broken graphs; substituting
+ * terrain there would lift sconces off walls, so they stay `0` forever.
+ *
+ * The whole file is pure — nodes in, metres out — which is what lets the stacking
+ * matrix be tested per kind without a canvas.
+ */
+import type { AnyNode } from '../schema';
+/**
+ * World Y of the site datum — the plane terrain heights are measured from.
+ *
+ * Terrain vertices are absolute world coordinates (the site group renders at the
+ * origin and `terrain-geometry` writes `origin + col * spacing` straight into the
+ * buffer), so the datum is a constant rather than a site property. It is named
+ * because the *comparison* against it is load-bearing, not the value: it is what
+ * separates "the ground" from every other horizontal surface in the scene.
+ */
+export declare const SITE_DATUM_Y = 0;
+/**
+ * How close a surface must sit to the datum to count as the ground.
+ *
+ * Loose enough to absorb float drift through a level's world matrix, tight enough
+ * that a ground slab (5 cm) still reads as a built surface rather than as terrain.
+ */
+export declare const SITE_DATUM_EPSILON = 0.0001;
+/** True when a world-space height is the site datum — i.e. the terrain's plane. */
+export declare function isSiteDatum(worldY: number): boolean;
+/**
+ * Whether the sculpted ground is what a node on `levelId` stands on — i.e.
+ * whether moving the terrain moves that node.
+ *
+ * Split out of `terrainSupportLift` so the invalidation rule that re-elevates
+ * nodes after a sculpt (`markTerrainSupportDependents`) tests grade-ness with
+ * the *same* predicate the resolver does. Two copies of this test would drift,
+ * and the failure is silent: a level the resolver drapes but the dirty rule
+ * skips leaves its contents frozen at the height the ground used to be.
+ *
+ * Deliberately independent of whether a field exists. A stroke that clears the
+ * terrain has to re-elevate exactly the nodes a stroke that creates it does, and
+ * asking about the field here would mark none of them on the way back down.
+ */
+export declare function isLevelAtSiteDatum(nodes: Record<string, AnyNode>, levelId: string): boolean;
+/**
+ * The lift, in level-local metres, that the sculpted ground provides to a node on
+ * `levelId` at level-local `x`/`z`. Null when terrain does not support this node —
+ * no sculpted ground, an unresolvable level, or a storey whose floor is not at
+ * grade.
+ *
+ * Null rather than 0 so callers keep their existing flat-ground path verbatim.
+ * That is what makes this change invisible to every scene that never touched
+ * terrain, which is nearly all of them.
+ */
+export declare function terrainSupportLift(nodes: Record<string, AnyNode>, levelId: string, x: number, z: number): number | null;
+//# sourceMappingURL=terrain-support.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terrain-support.d.ts","sourceRoot":"","sources":["../../src/lib/terrain-support.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,WAAW,CAAA;AAOnD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,IAAI,CAAA;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAO,CAAA;AAEtC,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR,MAAM,GAAG,IAAI,CAYf"}

package/dist/lib/terrain-support.js

@@ -0,0 +1,150 @@
+/**
+ * Terrain as the level base — the third and last place flat ground was assumed.
+ *
+ * `getFloorPlacedElevation` returns a *lift* added to a node's level-local Y, and
+ * two of its `0`-returns mean "supported by the level base". This module is what
+ * those two branches call so that "the level base" can mean the sculpted ground
+ * instead of the plane `y = 0`. The other `0`-returns are `+0` no-ops for
+ * wall/ceiling-attached items, non-`level` parents, and broken graphs; substituting
+ * terrain there would lift sconces off walls, so they stay `0` forever.
+ *
+ * The whole file is pure — nodes in, metres out — which is what lets the stacking
+ * matrix be tested per kind without a canvas.
+ */
+import { getLevelElevations } from '../services/storey';
+import { heightAt } from './terrain-field';
+import { terrainFieldOf } from './terrain-source';
+/**
+ * World Y of the site datum — the plane terrain heights are measured from.
+ *
+ * Terrain vertices are absolute world coordinates (the site group renders at the
+ * origin and `terrain-geometry` writes `origin + col * spacing` straight into the
+ * buffer), so the datum is a constant rather than a site property. It is named
+ * because the *comparison* against it is load-bearing, not the value: it is what
+ * separates "the ground" from every other horizontal surface in the scene.
+ */
+export const SITE_DATUM_Y = 0;
+/**
+ * How close a surface must sit to the datum to count as the ground.
+ *
+ * Loose enough to absorb float drift through a level's world matrix, tight enough
+ * that a ground slab (5 cm) still reads as a built surface rather than as terrain.
+ */
+export const SITE_DATUM_EPSILON = 1e-4;
+/** True when a world-space height is the site datum — i.e. the terrain's plane. */
+export function isSiteDatum(worldY) {
+    return Math.abs(worldY - SITE_DATUM_Y) < SITE_DATUM_EPSILON;
+}
+/**
+ * `getLevelElevations` memoized on the `nodes` record identity.
+ *
+ * Without this the stacking resolver is O(N) per node and therefore O(N²) per
+ * frame, since `FloorElevationSystem` calls it for every dirty floor-placed node.
+ * The scene store is immutable-by-convention, so the record identity is a correct
+ * version key — the same reasoning (and the same `WeakMap` shape) as
+ * `terrain-source`'s field cache and the spatial grid's `levelWallsCache`.
+ */
+const levelElevationCache = new WeakMap();
+function cachedLevelElevations(nodes) {
+    const cached = levelElevationCache.get(nodes);
+    if (cached)
+        return cached;
+    const elevations = getLevelElevations(nodes);
+    levelElevationCache.set(nodes, elevations);
+    return elevations;
+}
+function siteOf(nodes) {
+    for (const node of Object.values(nodes)) {
+        if (node?.type === 'site')
+            return node;
+    }
+    return null;
+}
+/**
+ * Level-local XZ → world XZ, through the building's transform.
+ *
+ * A level group carries only a Y offset (`LevelSystem` writes `position.y` and
+ * nothing else), so level-local XZ is building-local XZ; the building carries the
+ * site-space placement, and the site renders at the origin. Only the Y rotation
+ * matters — a building tipped in X or Z is not a thing the editor can produce.
+ */
+function levelLocalToWorldXZ(building, x, z) {
+    if (!building)
+        return [x, z];
+    const angle = building.rotation?.[1] ?? 0;
+    const [px, , pz] = building.position ?? [0, 0, 0];
+    if (angle === 0)
+        return [x + px, z + pz];
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    return [cos * x + sin * z + px, -sin * x + cos * z + pz];
+}
+/**
+ * Where a level sits relative to the datum, for the levels terrain can support.
+ *
+ * **Only the storey the level stack puts at the datum follows terrain.** An upper
+ * storey has a real floor, and draping it would sink its contents into the
+ * hillside under the building. The test is that storey's own base height against
+ * the datum — deliberately asked of `getLevelElevations`, the same function the
+ * renderer positions level groups with, so placement can never hold a second
+ * opinion about which storey is on the ground.
+ *
+ * Which storey that is follows from the stack, not from the ordinal: today the
+ * lowest ordinal anchors at 0, so a building with an ordinal `-1` level has *that*
+ * level at grade and its ground floor a storey up. When genuine below-grade
+ * stacking lands, this rule tracks it with no change here — an excavated basement
+ * will stop being at the datum, and stop being draped, on its own.
+ */
+function levelDatum(nodes, levelId) {
+    const elevation = cachedLevelElevations(nodes).get(levelId);
+    if (!elevation)
+        return null;
+    const building = elevation.buildingId
+        ? (nodes[elevation.buildingId] ?? null)
+        : null;
+    const datum = building?.position?.[1] ?? 0;
+    const baseWorldY = datum + elevation.baseY;
+    if (!isSiteDatum(baseWorldY))
+        return null;
+    return { building, baseWorldY };
+}
+/**
+ * Whether the sculpted ground is what a node on `levelId` stands on — i.e.
+ * whether moving the terrain moves that node.
+ *
+ * Split out of `terrainSupportLift` so the invalidation rule that re-elevates
+ * nodes after a sculpt (`markTerrainSupportDependents`) tests grade-ness with
+ * the *same* predicate the resolver does. Two copies of this test would drift,
+ * and the failure is silent: a level the resolver drapes but the dirty rule
+ * skips leaves its contents frozen at the height the ground used to be.
+ *
+ * Deliberately independent of whether a field exists. A stroke that clears the
+ * terrain has to re-elevate exactly the nodes a stroke that creates it does, and
+ * asking about the field here would mark none of them on the way back down.
+ */
+export function isLevelAtSiteDatum(nodes, levelId) {
+    return levelDatum(nodes, levelId) !== null;
+}
+/**
+ * The lift, in level-local metres, that the sculpted ground provides to a node on
+ * `levelId` at level-local `x`/`z`. Null when terrain does not support this node —
+ * no sculpted ground, an unresolvable level, or a storey whose floor is not at
+ * grade.
+ *
+ * Null rather than 0 so callers keep their existing flat-ground path verbatim.
+ * That is what makes this change invisible to every scene that never touched
+ * terrain, which is nearly all of them.
+ */
+export function terrainSupportLift(nodes, levelId, x, z) {
+    const site = siteOf(nodes);
+    const field = site ? terrainFieldOf(site) : null;
+    if (!field)
+        return null;
+    const datum = levelDatum(nodes, levelId);
+    if (!datum)
+        return null;
+    const [worldX, worldZ] = levelLocalToWorldXZ(datum.building, x, z);
+    // The lift is measured from the storey's own base, so a building sited on a
+    // datum other than 0 does not double-count it.
+    return heightAt(field, worldX, worldZ) - datum.baseWorldY;
+}

package/dist/lib/zone-quantities.d.ts

@@ -17,5 +17,5 @@ export type ZoneQuantityReport = {
     floorSurface: ZoneQuantityValue;
     volume: ZoneQuantityValue;
 };
-export declare function deriveZoneQuantityReport(zone: ZoneNode, sceneNodes: Record<string, AnyNode>): ZoneQuantityReport;
+export declare function deriveZoneQuantityReport(zone: ZoneNode, sceneNodes: Readonly<Record<string, AnyNode>>): ZoneQuantityReport;
 //# sourceMappingURL=zone-quantities.d.ts.map

package/dist/lib/zone-quantities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zone-quantities.d.ts","sourceRoot":"","sources":["../../src/lib/zone-quantities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAmC,QAAQ,EAAE,MAAM,WAAW,CAAA;AAOnF,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,cAAc,EAAE,WAAW,GAAG,eAAe,CAAA;IAC7C,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,YAAY,EAAE,iBAAiB,CAAA;IAC/B,MAAM,EAAE,iBAAiB,CAAA;CAC1B,CAAA;AA2HD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,kBAAkB,CA2GpB"}
+{"version":3,"file":"zone-quantities.d.ts","sourceRoot":"","sources":["../../src/lib/zone-quantities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAmC,QAAQ,EAAE,MAAM,WAAW,CAAA;AAYnF,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,cAAc,EAAE,WAAW,GAAG,eAAe,CAAA;IAC7C,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,WAAW,EAAE,iBAAiB,CAAA;IAC9B,YAAY,EAAE,iBAAiB,CAAA;IAC/B,MAAM,EAAE,iBAAiB,CAAA;CAC1B,CAAA;AA8bD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC5C,kBAAkB,CAmGpB"}