@pascal-app/core 1.0.0-beta.5 → 1.0.0

package/dist/schema/nodes/automatic-downspout.js

@@ -0,0 +1,237 @@
+import { getWallBaseElevationForNodes } from '../../hooks/spatial-grid/spatial-grid-manager';
+import { heightAt } from '../../lib/terrain-field';
+import { persistedTerrainFieldOf } from '../../lib/terrain-source';
+import { getLevelElevations } from '../../services/storey';
+import { computeGutterEaveY } from './gutter';
+const DEFAULT_MAX_RUN_PER_DOWNSPOUT_M = 10;
+const OUTLET_END_INSET_M = 0.16;
+const CONNECTION_TOLERANCE_M = 0.1;
+const CONNECTION_TOLERANCE_SQ = CONNECTION_TOLERANCE_M * CONNECTION_TOLERANCE_M;
+const FLAT_GROUND_Y = 0;
+// A point on the gutter's own mesh, expressed in gutter-mesh-local
+// coordinates: `alongX` is the signed distance from the gutter center along
+// its length, `outwardZ` the outward offset from the eave line. For a curved
+// run the flat (alongX, outwardZ) is bent onto the concentric arc descriptor
+// (matches the mapping the outlet lookup + gutter geometry use); a straight
+// gutter passes through unchanged.
+function gutterMeshPoint(gutter, alongX, outwardZ) {
+    const arc = gutter.arc;
+    if (!arc)
+        return [alongX, outwardZ];
+    const signedRef = (Math.sign(arc.centerZ) || 1) * arc.radius;
+    if (Math.abs(signedRef) < 1e-9)
+        return [alongX, outwardZ];
+    const phi = (alongX - arc.centerX) / signedRef;
+    const radial = outwardZ - arc.centerZ;
+    return [arc.centerX - radial * Math.sin(phi), arc.centerZ + radial * Math.cos(phi)];
+}
+function gutterPointInRoofFrame(gutter, segment, offset) {
+    const gutterRotation = gutter.rotation ?? 0;
+    const [meshX, meshZ] = gutterMeshPoint(gutter, offset, 0);
+    const localX = gutter.position[0] + Math.cos(gutterRotation) * meshX + Math.sin(gutterRotation) * meshZ;
+    const localZ = gutter.position[2] - Math.sin(gutterRotation) * meshX + Math.cos(gutterRotation) * meshZ;
+    if (!segment)
+        return [localX, localZ];
+    const segmentRotation = segment.rotation ?? 0;
+    const cos = Math.cos(segmentRotation);
+    const sin = Math.sin(segmentRotation);
+    return [
+        (segment.position?.[0] ?? 0) + localX * cos + localZ * sin,
+        (segment.position?.[2] ?? 0) - localX * sin + localZ * cos,
+    ];
+}
+function rotateAndTranslate(point, position, rotation) {
+    const cos = Math.cos(rotation);
+    const sin = Math.sin(rotation);
+    return [
+        (position?.[0] ?? 0) + point[0] * cos + point[1] * sin,
+        (position?.[2] ?? 0) - point[0] * sin + point[1] * cos,
+    ];
+}
+function gutterFloorMidZ(gutter) {
+    const size = Math.max(0.04, gutter.size);
+    if (gutter.profile === 'half-round')
+        return size;
+    if (gutter.profile === 'box')
+        return size / 2;
+    return size * 0.4;
+}
+// The gutter's mount height in the host segment's local frame. Lean-to gutters
+// can be raised to a shared eave line (stored as `leanToGutterEaveY` metadata by
+// the lean-to assembly); the renderer mounts there rather than at the segment's
+// own eave, so the outlet elevation must read the prescribed value when present.
+function prescribedGutterEaveY(gutter) {
+    const metadata = gutter.metadata;
+    if (!(metadata && typeof metadata === 'object' && !Array.isArray(metadata)))
+        return null;
+    const value = metadata.leanToGutterEaveY;
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+export function resolveAutomaticDownspoutLength(nodes, segment, gutter, outletOffset) {
+    const roofCandidate = segment.parentId ? nodes[segment.parentId] : undefined;
+    const roof = roofCandidate?.type === 'roof' ? roofCandidate : undefined;
+    const roofParent = roof?.parentId ? nodes[roof.parentId] : undefined;
+    const leanTo = roofParent?.type === 'lean-to-extension' ? roofParent : undefined;
+    const wallCandidate = leanTo?.parentId ? nodes[leanTo.parentId] : undefined;
+    const wall = wallCandidate?.type === 'wall' ? wallCandidate : undefined;
+    const levelCandidate = wall?.parentId ? nodes[wall.parentId] : roofParent;
+    const level = levelCandidate?.type === 'level' ? levelCandidate : undefined;
+    const buildingCandidate = level?.parentId ? nodes[level.parentId] : undefined;
+    const building = buildingCandidate?.type === 'building' ? buildingCandidate : undefined;
+    const gutterRotation = gutter.rotation ?? 0;
+    const gutterFloorPoint = rotateAndTranslate(gutterMeshPoint(gutter, outletOffset, gutterFloorMidZ(gutter)), gutter.position, gutterRotation);
+    const roofPoint = rotateAndTranslate(gutterFloorPoint, segment.position, segment.rotation ?? 0);
+    const leanToPoint = rotateAndTranslate(roofPoint, roof?.position, roof?.rotation ?? 0);
+    const wallLocalPoint = leanTo
+        ? rotateAndTranslate(leanToPoint, leanTo.position, leanTo.rotation[1])
+        : leanToPoint;
+    const wallAngle = wall ? Math.atan2(wall.end[1] - wall.start[1], wall.end[0] - wall.start[0]) : 0;
+    const levelPoint = wall
+        ? rotateAndTranslate(wallLocalPoint, [wall.start[0], 0, wall.start[1]], -wallAngle)
+        : wallLocalPoint;
+    const buildingRotation = building?.rotation?.[1] ?? 0;
+    const worldPoint = rotateAndTranslate(levelPoint, building?.position, buildingRotation);
+    const site = Object.values(nodes).find((node) => node?.type === 'site');
+    const terrain = persistedTerrainFieldOf(site);
+    const groundY = terrain ? heightAt(terrain, worldPoint[0], worldPoint[1]) : FLAT_GROUND_Y;
+    const levelBaseY = level ? (getLevelElevations(nodes).get(level.id)?.baseY ?? 0) : 0;
+    const outletWorldY = (building?.position?.[1] ?? 0) +
+        levelBaseY +
+        (wall ? getWallBaseElevationForNodes(wall, nodes) : 0) +
+        (leanTo?.position[1] ?? 0) +
+        (roof?.position?.[1] ?? 0) +
+        (segment.position?.[1] ?? 0) +
+        (prescribedGutterEaveY(gutter) ?? computeGutterEaveY(segment)) -
+        Math.max(0.04, gutter.size);
+    return Math.max(0.1, outletWorldY - groundY);
+}
+function distanceSquared(a, b) {
+    return (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2;
+}
+function find(parent, value) {
+    let root = value;
+    while (parent[root] !== root)
+        root = parent[root];
+    while (parent[value] !== value) {
+        const next = parent[value];
+        parent[value] = root;
+        value = next;
+    }
+    return root;
+}
+function union(parent, a, b) {
+    const rootA = find(parent, a);
+    const rootB = find(parent, b);
+    if (rootA !== rootB)
+        parent[rootB] = rootA;
+}
+function addUniquePlacement(placements, seen, gutter, offset) {
+    const key = `${gutter.id}:${offset.toFixed(6)}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    placements.push({ gutterId: gutter.id, offset });
+}
+export function planAutomaticDownspouts({ segments, gutters, downspouts, maxRunPerDownspout = DEFAULT_MAX_RUN_PER_DOWNSPOUT_M, }) {
+    if (gutters.length === 0)
+        return [];
+    const segmentById = new Map(segments.map((segment) => [segment.id, segment]));
+    const parent = gutters.map((_, index) => index);
+    const ends = [];
+    for (let gutterIndex = 0; gutterIndex < gutters.length; gutterIndex++) {
+        const gutter = gutters[gutterIndex];
+        const halfLength = Math.max(0, gutter.length) / 2;
+        const segment = gutter.roofSegmentId ? segmentById.get(gutter.roofSegmentId) : undefined;
+        ends.push({
+            gutterIndex,
+            offset: halfLength,
+            point: gutterPointInRoofFrame(gutter, segment, halfLength),
+        }, {
+            gutterIndex,
+            offset: -halfLength,
+            point: gutterPointInRoofFrame(gutter, segment, -halfLength),
+        });
+    }
+    const connectedEnds = new Set();
+    for (let i = 0; i < ends.length; i++) {
+        for (let j = i + 1; j < ends.length; j++) {
+            const a = ends[i];
+            const b = ends[j];
+            if (a.gutterIndex === b.gutterIndex)
+                continue;
+            if (distanceSquared(a.point, b.point) > CONNECTION_TOLERANCE_SQ)
+                continue;
+            connectedEnds.add(i);
+            connectedEnds.add(j);
+            union(parent, a.gutterIndex, b.gutterIndex);
+        }
+    }
+    const componentIndices = new Map();
+    for (let index = 0; index < gutters.length; index++) {
+        const root = find(parent, index);
+        const indices = componentIndices.get(root) ?? [];
+        indices.push(index);
+        componentIndices.set(root, indices);
+    }
+    const gutterIndexById = new Map(gutters.map((gutter, index) => [gutter.id, index]));
+    const placements = [];
+    const seen = new Set();
+    const safeMaxRun = Math.max(0.5, maxRunPerDownspout);
+    for (const indices of componentIndices.values()) {
+        const indexSet = new Set(indices);
+        const totalLength = indices.reduce((sum, index) => sum + Math.max(0, gutters[index]?.length ?? 0), 0);
+        const requiredCount = Math.max(1, Math.ceil(totalLength / safeMaxRun));
+        const manualCount = downspouts.filter((downspout) => {
+            if (!downspout.gutterId)
+                return false;
+            const gutterIndex = gutterIndexById.get(downspout.gutterId);
+            if (gutterIndex === undefined || !indexSet.has(gutterIndex))
+                return false;
+            const gutter = gutters[gutterIndex];
+            return Boolean(gutter &&
+                downspout.outletId &&
+                (gutter.outlets ?? []).some((outlet) => outlet.id === downspout.outletId));
+        }).length;
+        let remaining = Math.max(0, requiredCount - manualCount);
+        if (remaining === 0)
+            continue;
+        const freeEnds = ends.filter((end, endIndex) => indexSet.has(end.gutterIndex) && !connectedEnds.has(endIndex));
+        for (const end of freeEnds) {
+            if (remaining === 0)
+                break;
+            const gutter = gutters[end.gutterIndex];
+            const bound = Math.max(0, gutter.length / 2 - OUTLET_END_INSET_M);
+            addUniquePlacement(placements, seen, gutter, end.offset >= 0 ? bound : -bound);
+            remaining--;
+        }
+        if (remaining === 0)
+            continue;
+        const componentGutters = indices
+            .map((index) => gutters[index])
+            .sort((a, b) => b.length - a.length || a.id.localeCompare(b.id));
+        const interiorCandidates = [];
+        let round = 0;
+        while (interiorCandidates.length < remaining) {
+            let addedThisRound = 0;
+            for (const gutter of componentGutters) {
+                const interiorSlots = Math.max(1, Math.ceil(gutter.length / safeMaxRun) - 1);
+                if (round >= interiorSlots)
+                    continue;
+                const offset = -gutter.length / 2 + (gutter.length * (round + 1)) / (interiorSlots + 1);
+                interiorCandidates.push({ gutterId: gutter.id, offset });
+                addedThisRound++;
+            }
+            if (addedThisRound === 0)
+                break;
+            round++;
+        }
+        for (const candidate of interiorCandidates) {
+            if (remaining === 0)
+                break;
+            const gutter = gutters[gutterIndexById.get(candidate.gutterId)];
+            addUniquePlacement(placements, seen, gutter, candidate.offset);
+            remaining--;
+        }
+    }
+    return placements;
+}

package/dist/schema/nodes/block.d.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+export declare const BlockVertex: z.ZodObject<{
+    id: z.ZodString;
+    position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+}, z.core.$strip>;
+export declare const BlockEdge: z.ZodObject<{
+    id: z.ZodString;
+    vertexIds: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+}, z.core.$strip>;
+export declare const BlockFace: z.ZodObject<{
+    id: z.ZodString;
+    vertexIds: z.ZodArray<z.ZodString>;
+    materialSlot: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const BlockTopologyShape: z.ZodObject<{
+    vertices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        vertexIds: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    }, z.core.$strip>>;
+    faces: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        vertexIds: z.ZodArray<z.ZodString>;
+        materialSlot: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlockVertex = z.infer<typeof BlockVertex>;
+export type BlockEdge = z.infer<typeof BlockEdge>;
+export type BlockFace = z.infer<typeof BlockFace>;
+export type BlockTopology = z.infer<typeof BlockTopologyShape>;
+export type BlockFaceFrame = {
+    origin: [number, number, number];
+    xAxis: [number, number, number];
+    yAxis: [number, number, number];
+    normal: [number, number, number];
+};
+export declare function getBlockFaceNormal(topology: BlockTopology, face: BlockFace): [number, number, number] | null;
+export declare function getBlockFaceCentroid(topology: BlockTopology, face: BlockFace): [number, number, number] | null;
+export declare function getBlockFaceFrame(topology: BlockTopology, faceId: string): BlockFaceFrame | null;
+export type BlockTopologyIssue = {
+    path: (string | number)[];
+    message: string;
+};
+export declare function blockUndirectedEdgeKey(a: string, b: string): string;
+export declare function inspectBlockTopology(topology: BlockTopology): BlockTopologyIssue[];
+export declare const BlockTopology: z.ZodObject<{
+    vertices: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        vertexIds: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    }, z.core.$strip>>;
+    faces: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        vertexIds: z.ZodArray<z.ZodString>;
+        materialSlot: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function createBoxBlockTopology(width?: number, height?: number, depth?: number): BlockTopology;
+export declare const BlockNode: z.ZodObject<{
+    object: z.ZodDefault<z.ZodLiteral<"node">>;
+    name: z.ZodOptional<z.ZodString>;
+    parentId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    visible: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    camera: z.ZodOptional<z.ZodObject<{
+        position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        target: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            perspective: "perspective";
+            orthographic: "orthographic";
+        }>>;
+        fov: z.ZodOptional<z.ZodNumber>;
+        zoom: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    metadata: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    id: z.ZodDefault<z.ZodTemplateLiteral<`block_${string}`>>;
+    type: z.ZodDefault<z.ZodLiteral<"block">>;
+    children: z.ZodDefault<z.ZodArray<z.ZodDefault<z.ZodTemplateLiteral<`item_${string}`>>>>;
+    position: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    rotation: z.ZodDefault<z.ZodNumber>;
+    supportSlabId: z.ZodOptional<z.ZodString>;
+    topology: z.ZodDefault<z.ZodObject<{
+        vertices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            position: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strip>>;
+        edges: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            vertexIds: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+        }, z.core.$strip>>;
+        faces: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            vertexIds: z.ZodArray<z.ZodString>;
+            materialSlot: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    slots: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    slotNames: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type BlockNode = z.infer<typeof BlockNode>;
+export {};
+//# sourceMappingURL=block.d.ts.map

package/dist/schema/nodes/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/block.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,WAAW;;;iBAGtB,CAAA;AAEF,eAAO,MAAM,SAAS;;;iBAGpB,CAAA;AAEF,eAAO,MAAM,SAAS;;;;iBAIpB,CAAA;AAEF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;iBAItB,CAAA;AAEF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA;AACrD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AACjD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA;AACjD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE9D,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAAA;AAQD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,SAAS,GACd,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAgBjC;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,SAAS,GACd,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAWjC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAuBhG;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,UAE1D;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,EAAE,CAgElF;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;iBAIxB,CAAA;AAEF,wBAAgB,sBAAsB,CAAC,KAAK,SAAI,EAAE,MAAM,SAAM,EAAE,KAAK,SAAI,GAAG,aAAa,CAqCxF;AAED,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkBpB,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAA"}

package/dist/schema/nodes/block.js

@@ -0,0 +1,207 @@
+import dedent from 'dedent';
+import { z } from 'zod';
+import { BaseNode, nodeType, objectId } from '../base';
+import { ItemNode } from './item';
+export const BlockVertex = z.object({
+    id: z.string().min(1),
+    position: z.tuple([z.number(), z.number(), z.number()]),
+});
+export const BlockEdge = z.object({
+    id: z.string().min(1),
+    vertexIds: z.tuple([z.string().min(1), z.string().min(1)]),
+});
+export const BlockFace = z.object({
+    id: z.string().min(1),
+    vertexIds: z.array(z.string().min(1)).min(3),
+    materialSlot: z.string().min(1).default('body'),
+});
+const BlockTopologyShape = z.object({
+    vertices: z.array(BlockVertex),
+    edges: z.array(BlockEdge),
+    faces: z.array(BlockFace),
+});
+function normalizeBlockVector(vector) {
+    const length = Math.hypot(vector[0], vector[1], vector[2]);
+    if (length < 1e-8)
+        return null;
+    return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+export function getBlockFaceNormal(topology, face) {
+    const vertices = new Map(topology.vertices.map((vertex) => [vertex.id, vertex.position]));
+    const positions = face.vertexIds
+        .map((id) => vertices.get(id))
+        .filter((value) => !!value);
+    if (positions.length < 3)
+        return null;
+    const normal = [0, 0, 0];
+    for (let index = 0; index < positions.length; index += 1) {
+        const current = positions[index];
+        const next = positions[(index + 1) % positions.length];
+        normal[0] += (current[1] - next[1]) * (current[2] + next[2]);
+        normal[1] += (current[2] - next[2]) * (current[0] + next[0]);
+        normal[2] += (current[0] - next[0]) * (current[1] + next[1]);
+    }
+    return normalizeBlockVector(normal);
+}
+export function getBlockFaceCentroid(topology, face) {
+    const vertices = new Map(topology.vertices.map((vertex) => [vertex.id, vertex.position]));
+    const positions = face.vertexIds
+        .map((id) => vertices.get(id))
+        .filter((value) => !!value);
+    if (positions.length !== face.vertexIds.length || positions.length === 0)
+        return null;
+    const sum = positions.reduce((total, position) => [total[0] + position[0], total[1] + position[1], total[2] + position[2]], [0, 0, 0]);
+    return [sum[0] / positions.length, sum[1] / positions.length, sum[2] / positions.length];
+}
+export function getBlockFaceFrame(topology, faceId) {
+    const face = topology.faces.find((candidate) => candidate.id === faceId);
+    if (!face)
+        return null;
+    const origin = getBlockFaceCentroid(topology, face);
+    const normal = getBlockFaceNormal(topology, face);
+    if (!(origin && normal))
+        return null;
+    const horizontal = [normal[2], 0, -normal[0]];
+    const xAxis = normalizeBlockVector(horizontal) ??
+        normalizeBlockVector([
+            1 - normal[0] * normal[0],
+            -normal[0] * normal[1],
+            -normal[0] * normal[2],
+        ]);
+    if (!xAxis)
+        return null;
+    const yAxis = normalizeBlockVector([
+        normal[1] * xAxis[2] - normal[2] * xAxis[1],
+        normal[2] * xAxis[0] - normal[0] * xAxis[2],
+        normal[0] * xAxis[1] - normal[1] * xAxis[0],
+    ]);
+    if (!yAxis)
+        return null;
+    return { origin, xAxis, yAxis, normal };
+}
+export function blockUndirectedEdgeKey(a, b) {
+    return a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+}
+export function inspectBlockTopology(topology) {
+    const issues = [];
+    const vertexIds = new Set();
+    const edgeIds = new Set();
+    const faceIds = new Set();
+    const edgeKeys = new Set();
+    topology.vertices.forEach((vertex, index) => {
+        if (vertexIds.has(vertex.id)) {
+            issues.push({ path: ['vertices', index, 'id'], message: `Duplicate vertex id: ${vertex.id}` });
+        }
+        vertexIds.add(vertex.id);
+    });
+    topology.edges.forEach((edge, index) => {
+        if (edgeIds.has(edge.id)) {
+            issues.push({ path: ['edges', index, 'id'], message: `Duplicate edge id: ${edge.id}` });
+        }
+        edgeIds.add(edge.id);
+        const [a, b] = edge.vertexIds;
+        if (a === b) {
+            issues.push({ path: ['edges', index, 'vertexIds'], message: 'An edge needs two vertices' });
+        }
+        edge.vertexIds.forEach((vertexId, vertexIndex) => {
+            if (!vertexIds.has(vertexId)) {
+                issues.push({
+                    path: ['edges', index, 'vertexIds', vertexIndex],
+                    message: `Unknown vertex id: ${vertexId}`,
+                });
+            }
+        });
+        const key = blockUndirectedEdgeKey(a, b);
+        if (edgeKeys.has(key)) {
+            issues.push({ path: ['edges', index], message: `Duplicate edge: ${a}–${b}` });
+        }
+        edgeKeys.add(key);
+    });
+    topology.faces.forEach((face, index) => {
+        if (faceIds.has(face.id)) {
+            issues.push({ path: ['faces', index, 'id'], message: `Duplicate face id: ${face.id}` });
+        }
+        faceIds.add(face.id);
+        if (new Set(face.vertexIds).size < 3) {
+            issues.push({ path: ['faces', index, 'vertexIds'], message: 'A face needs three vertices' });
+        }
+        face.vertexIds.forEach((vertexId, vertexIndex) => {
+            if (!vertexIds.has(vertexId)) {
+                issues.push({
+                    path: ['faces', index, 'vertexIds', vertexIndex],
+                    message: `Unknown vertex id: ${vertexId}`,
+                });
+            }
+            const nextVertexId = face.vertexIds[(vertexIndex + 1) % face.vertexIds.length];
+            if (nextVertexId && !edgeKeys.has(blockUndirectedEdgeKey(vertexId, nextVertexId))) {
+                issues.push({
+                    path: ['faces', index, 'vertexIds', vertexIndex],
+                    message: `Missing edge for face boundary: ${vertexId}–${nextVertexId}`,
+                });
+            }
+        });
+    });
+    return issues;
+}
+export const BlockTopology = BlockTopologyShape.superRefine((topology, context) => {
+    for (const issue of inspectBlockTopology(topology)) {
+        context.addIssue({ code: 'custom', path: issue.path, message: issue.message });
+    }
+});
+export function createBoxBlockTopology(width = 2, height = 2.4, depth = 2) {
+    const halfWidth = width / 2;
+    const halfDepth = depth / 2;
+    return {
+        vertices: [
+            { id: 'v0', position: [-halfWidth, 0, -halfDepth] },
+            { id: 'v1', position: [halfWidth, 0, -halfDepth] },
+            { id: 'v2', position: [halfWidth, 0, halfDepth] },
+            { id: 'v3', position: [-halfWidth, 0, halfDepth] },
+            { id: 'v4', position: [-halfWidth, height, -halfDepth] },
+            { id: 'v5', position: [halfWidth, height, -halfDepth] },
+            { id: 'v6', position: [halfWidth, height, halfDepth] },
+            { id: 'v7', position: [-halfWidth, height, halfDepth] },
+        ],
+        edges: [
+            { id: 'e0', vertexIds: ['v0', 'v1'] },
+            { id: 'e1', vertexIds: ['v1', 'v2'] },
+            { id: 'e2', vertexIds: ['v2', 'v3'] },
+            { id: 'e3', vertexIds: ['v3', 'v0'] },
+            { id: 'e4', vertexIds: ['v4', 'v5'] },
+            { id: 'e5', vertexIds: ['v5', 'v6'] },
+            { id: 'e6', vertexIds: ['v6', 'v7'] },
+            { id: 'e7', vertexIds: ['v7', 'v4'] },
+            { id: 'e8', vertexIds: ['v0', 'v4'] },
+            { id: 'e9', vertexIds: ['v1', 'v5'] },
+            { id: 'e10', vertexIds: ['v2', 'v6'] },
+            { id: 'e11', vertexIds: ['v3', 'v7'] },
+        ],
+        faces: [
+            { id: 'f-bottom', vertexIds: ['v0', 'v1', 'v2', 'v3'], materialSlot: 'body' },
+            { id: 'f-top', vertexIds: ['v4', 'v7', 'v6', 'v5'], materialSlot: 'body' },
+            { id: 'f-front', vertexIds: ['v0', 'v4', 'v5', 'v1'], materialSlot: 'body' },
+            { id: 'f-right', vertexIds: ['v1', 'v5', 'v6', 'v2'], materialSlot: 'body' },
+            { id: 'f-back', vertexIds: ['v2', 'v6', 'v7', 'v3'], materialSlot: 'body' },
+            { id: 'f-left', vertexIds: ['v3', 'v7', 'v4', 'v0'], materialSlot: 'body' },
+        ],
+    };
+}
+export const BlockNode = BaseNode.extend({
+    id: objectId('block'),
+    type: nodeType('block'),
+    children: z.array(ItemNode.shape.id).default([]),
+    position: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
+    rotation: z.number().default(0),
+    supportSlabId: z.string().optional(),
+    topology: BlockTopology.default(createBoxBlockTopology),
+    slots: z.record(z.string(), z.string()).default({}),
+    slotNames: z.record(z.string(), z.string().min(1)).default({ body: 'Body' }),
+}).describe(dedent `
+  block node - a topology-backed editable solid.
+  - children: items hosted on persistent topology faces
+  - topology: persistent vertices, edges, and ordered face loops with stable IDs
+  - position/rotation: level-local placement transform
+  - supportSlabId: persisted placement surface that prevents later slabs from lifting the mesh
+  - slots: material references keyed by face materialSlot; an unbound body uses the wall-role default
+  - slotNames: user-facing names for stable material slots; body is the permanent default slot
+`);

package/dist/schema/nodes/box-vent.d.ts

@@ -1,4 +1,9 @@
 import { z } from 'zod';
+export declare const BoxVentMaterialRole: z.ZodEnum<{
+    base: "base";
+    top: "top";
+}>;
+export type BoxVentMaterialRole = z.infer<typeof BoxVentMaterialRole>;
 export declare const BoxVentNode: z.ZodObject<{
     object: z.ZodDefault<z.ZodLiteral<"node">>;
     name: z.ZodOptional<z.ZodString>;
@@ -14,7 +19,7 @@ export declare const BoxVentNode: z.ZodObject<{
         fov: z.ZodOptional<z.ZodNumber>;
         zoom: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
-    metadata: z.ZodDefault<z.ZodOptional<z.ZodJSONSchema>>;
+    metadata: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     id: z.ZodDefault<z.ZodTemplateLiteral<`bvent_${string}`>>;
     type: z.ZodDefault<z.ZodLiteral<"box-vent">>;
     material: z.ZodOptional<z.ZodObject<{
@@ -49,6 +54,7 @@ export declare const BoxVentNode: z.ZodObject<{
             scale: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    slots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     materialPreset: z.ZodDefault<z.ZodString>;
     roofSegmentId: z.ZodOptional<z.ZodString>;
     position: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
@@ -68,7 +74,7 @@ export declare const BoxVentNode: z.ZodObject<{
         box: "box";
         cap: "cap";
         dome: "dome";
-    }>>>;
+    }>>, unknown>;
 }, z.core.$strip>;
 export type BoxVentNode = z.infer<typeof BoxVentNode>;
 //# sourceMappingURL=box-vent.d.ts.map

package/dist/schema/nodes/box-vent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box-vent.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/box-vent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiEvB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA"}
+{"version":3,"file":"box-vent.d.ts","sourceRoot":"","sources":["../../../src/schema/nodes/box-vent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,mBAAmB;;;EAA0B,CAAA;AAC1D,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAErE,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEvB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAA"}

package/dist/schema/nodes/box-vent.js

@@ -2,10 +2,12 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { BaseNode, nodeType, objectId } from '../base';
 import { MaterialSchema } from '../material';
+export const BoxVentMaterialRole = z.enum(['base', 'top']);
 export const BoxVentNode = BaseNode.extend({
     id: objectId('bvent'),
     type: nodeType('box-vent'),
     material: MaterialSchema.optional(),
+    slots: z.record(z.string(), z.string()).optional(),
     // Default to the white preset so newly-placed vents read as clean
     // painted metal — and so the paint inspector shows "White" as the
     // current selection instead of an empty "no material" state, which

package/dist/schema/nodes/building.d.ts

@@ -14,7 +14,7 @@ export declare const BuildingNode: z.ZodObject<{
         fov: z.ZodOptional<z.ZodNumber>;
         zoom: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
-    metadata: z.ZodDefault<z.ZodOptional<z.ZodJSONSchema>>;
+    metadata: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     id: z.ZodDefault<z.ZodTemplateLiteral<`building_${string}`>>;
     type: z.ZodDefault<z.ZodLiteral<"building">>;
     children: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodDefault<z.ZodTemplateLiteral<`level_${string}`>>, z.ZodDefault<z.ZodTemplateLiteral<`elevator_${string}`>>]>>>;