@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/sceneElements/compiler.js

@@ -0,0 +1,976 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileSceneElementsBundle = compileSceneElementsBundle;
+exports.compileSceneElements = compileSceneElements;
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const source_1 = require("../terrain/source");
+const source_2 = require("../placements/source");
+const meshCells_1 = require("./meshCells");
+const devices_1 = require("./devices");
+const DEFAULT_MATERIAL = {
+    color: '#d8d2c8',
+    roughness: 0.82,
+    metalness: 0,
+};
+function finite(value, label) {
+    if (!Number.isFinite(value))
+        throw new Error(`${label} must be finite`);
+    return value;
+}
+function positive(value, label) {
+    finite(value, label);
+    if (value <= 0)
+        throw new Error(`${label} must be greater than zero`);
+    return value;
+}
+function id(value, label) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value)) {
+        throw new Error(`${label} must be a stable Scene id`);
+    }
+    return value;
+}
+function vec3(value, label) {
+    if (!Array.isArray(value) || value.length !== 3)
+        throw new Error(`${label} must contain three numbers`);
+    return value.map((part, index) => finite(part, `${label}[${index}]`));
+}
+function inlineMaterial(input) {
+    const resolved = { ...DEFAULT_MATERIAL, ...input };
+    if (!/^#[0-9a-fA-F]{6}$/.test(resolved.color))
+        throw new Error(`material color must be #RRGGBB`);
+    if (resolved.roughness < 0 || resolved.roughness > 1)
+        throw new Error('material roughness must be between 0 and 1');
+    if (resolved.metalness < 0 || resolved.metalness > 1)
+        throw new Error('material metalness must be between 0 and 1');
+    return resolved;
+}
+function materialIdPart(value) {
+    id(value, 'material id');
+    return value;
+}
+/**
+ * A named `materials` entry is a compile-time-only alias for one inline
+ * color (ADR-0004 P6: the Vault material pin this used to validate —
+ * assetId/revision/integritySha256/bytes/defaults — is gone; every surface
+ * is its exact inline color now, never a Vault-backed Scene resource).
+ */
+function compileMaterials(input) {
+    const compiled = new Map();
+    for (const [key, material] of Object.entries(input ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+        materialIdPart(key);
+        compiled.set(key, { fallback: inlineMaterial(material) });
+    }
+    return compiled;
+}
+function resolveMaterial(input, catalog) {
+    if (input && 'ref' in input) {
+        const compiled = catalog.get(input.ref);
+        if (!compiled)
+            throw new Error(`unknown material ref "${input.ref}"`);
+        return { fallback: compiled.fallback, sceneMaterialId: null };
+    }
+    return { fallback: inlineMaterial(input), sceneMaterialId: null };
+}
+function yawQuaternion(degrees) {
+    finite(degrees, 'rotationYDeg');
+    const radians = degrees * Math.PI / 180;
+    return [0, Math.sin(radians / 2), 0, Math.cos(radians / 2)];
+}
+function quaternion(value, label) {
+    if (!Array.isArray(value) || value.length !== 4)
+        throw new Error(`${label} must contain four numbers`);
+    const parts = value.map((part, index) => finite(part, `${label}[${index}]`));
+    const length = Math.hypot(...parts);
+    if (length < 1e-8)
+        throw new Error(`${label} must not be zero length`);
+    return parts.map((part) => part / length);
+}
+function rotatedBoxBounds(position, size, rotation) {
+    const [x, y, z, w] = rotation;
+    const matrix = [
+        [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+        [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+        [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+    ];
+    const half = size.map((part) => part / 2);
+    const extent = matrix.map((row) => row.reduce((sum, part, axis) => sum + Math.abs(part) * half[axis], 0));
+    return {
+        min: position.map((part, axis) => part - extent[axis]),
+        max: position.map((part, axis) => part + extent[axis]),
+    };
+}
+function expandBounds(a, b) {
+    if (!a)
+        return { min: [...b.min], max: [...b.max] };
+    return {
+        min: a.min.map((value, axis) => Math.min(value, b.min[axis])),
+        max: a.max.map((value, axis) => Math.max(value, b.max[axis])),
+    };
+}
+function translateBounds(bounds, position) {
+    return {
+        min: bounds.min.map((value, axis) => value + position[axis]),
+        max: bounds.max.map((value, axis) => value + position[axis]),
+    };
+}
+function addVec3(a, b) {
+    return a.map((value, axis) => value + b[axis]);
+}
+function elementId(value, seen) {
+    id(value, 'element id');
+    if (seen.has(value))
+        throw new Error(`duplicate semantic element id "${value}"`);
+    seen.add(value);
+    return value;
+}
+function streamPolicy(input, inherited) {
+    const priority = input?.priority ?? inherited.priority;
+    if (!Number.isInteger(priority) || priority < 0 || priority > 1000) {
+        throw new Error('stream priority must be an integer between 0 and 1000');
+    }
+    return { mode: input?.mode ?? inherited.mode, priority };
+}
+function inheritProperties(input, inherited, defaults) {
+    const role = input.role ?? defaults?.role ?? inherited.role;
+    const defaultedStream = defaults?.streamMode && input.stream?.mode === undefined
+        ? { ...inherited.stream, mode: defaults.streamMode }
+        : inherited.stream;
+    return {
+        material: input.material ?? inherited.material,
+        collision: input.collision ?? inherited.collision,
+        role,
+        stream: streamPolicy(input.stream, defaultedStream),
+    };
+}
+function leafGeometry(element) {
+    if (element.type === 'wall') {
+        const startX = finite(element.start[0], `${element.id}.start[0]`);
+        const startZ = finite(element.start[1], `${element.id}.start[1]`);
+        const endX = finite(element.end[0], `${element.id}.end[0]`);
+        const endZ = finite(element.end[1], `${element.id}.end[1]`);
+        const height = positive(element.height, `${element.id}.height`);
+        const thickness = positive(element.thickness, `${element.id}.thickness`);
+        const length = Math.hypot(endX - startX, endZ - startZ);
+        positive(length, `${element.id} wall length`);
+        const baseY = finite(element.baseY ?? 0, `${element.id}.baseY`);
+        const halfThickness = thickness / 2;
+        return {
+            position: [(startX + endX) / 2, baseY + height / 2, (startZ + endZ) / 2],
+            size: [length, height, thickness],
+            rotation: yawQuaternion(-Math.atan2(endZ - startZ, endX - startX) * 180 / Math.PI),
+            bounds: {
+                min: [Math.min(startX, endX) - halfThickness, baseY, Math.min(startZ, endZ) - halfThickness],
+                max: [Math.max(startX, endX) + halfThickness, baseY + height, Math.max(startZ, endZ) + halfThickness],
+            },
+            slot: 'wall',
+        };
+    }
+    if (element.type !== 'primitive') {
+        const width = positive(element.size[0], `${element.id}.size[0]`);
+        const depth = positive(element.size[1], `${element.id}.size[1]`);
+        const thickness = positive(element.thickness, `${element.id}.thickness`);
+        const x = finite(element.center[0], `${element.id}.center[0]`);
+        const z = finite(element.center[1], `${element.id}.center[1]`);
+        const y = finite(element.elevation, `${element.id}.elevation`);
+        return {
+            position: [x, y, z],
+            size: [width, thickness, depth],
+            rotation: [0, 0, 0, 1],
+            bounds: {
+                min: [x - width / 2, y - thickness / 2, z - depth / 2],
+                max: [x + width / 2, y + thickness / 2, z + depth / 2],
+            },
+            slot: element.type,
+        };
+    }
+    const position = vec3(element.position, `${element.id}.position`);
+    const size = vec3(element.size, `${element.id}.size`).map((part, axis) => positive(part, `${element.id}.size[${axis}]`));
+    if (element.rotation !== undefined && element.rotationYDeg !== undefined) {
+        throw new Error(`${element.id} must use rotation or rotationYDeg, not both`);
+    }
+    const rotation = element.rotation !== undefined
+        ? quaternion(element.rotation, `${element.id}.rotation`)
+        : yawQuaternion(element.rotationYDeg ?? 0);
+    return {
+        position,
+        size,
+        rotation,
+        bounds: rotatedBoxBounds(position, size, rotation),
+        slot: element.slot ?? 'structure',
+    };
+}
+function compileLeaf(element, parent, streamGroup, materials, inherited, worldOffset) {
+    const geometry = leafGeometry(element);
+    const nodeId = `node.${element.id}`;
+    const primitiveId = `primitive.${element.id}`;
+    const surfaceId = `surface.${element.id}`;
+    const collisionSetId = `collision.${element.id}`;
+    const properties = inheritProperties(element, inherited);
+    const collisionEnabled = properties.collision;
+    const resolvedMaterial = resolveMaterial(properties.material, materials);
+    const node = {
+        id: nodeId,
+        parent,
+        transform: {
+            position: geometry.position,
+            rotation: geometry.rotation,
+            scale: [1, 1, 1],
+        },
+        streamGroup,
+        components: [
+            {
+                type: 'render.primitive',
+                primitive: {
+                    id: primitiveId,
+                    shape: 'box',
+                    size: geometry.size,
+                    material: resolvedMaterial.fallback,
+                },
+                castShadow: element.type !== 'floor',
+                receiveShadow: true,
+            },
+            { type: 'surface.bindings', surfaces: [surfaceId] },
+            ...(collisionEnabled ? [{ type: 'collision.proxy-set', set: collisionSetId }] : []),
+        ],
+    };
+    return {
+        node,
+        bounds: translateBounds(geometry.bounds, worldOffset),
+        surface: {
+            id: surfaceId,
+            slot: geometry.slot,
+            node: nodeId,
+            selector: { primitiveIds: [primitiveId] },
+            default: resolvedMaterial.sceneMaterialId === null
+                ? { kind: 'source' }
+                : { kind: 'material', material: resolvedMaterial.sceneMaterialId },
+            overridePolicy: { allowed: false, roles: [], parameters: [] },
+        },
+        collisionSet: collisionEnabled ? {
+            id: collisionSetId,
+            node: nodeId,
+            static: [{
+                    id: `collider.${element.id}`,
+                    shape: 'box',
+                    center: [0, 0, 0],
+                    halfExtents: geometry.size.map((part) => part / 2),
+                    surface: surfaceId,
+                }],
+        } : null,
+    };
+}
+function compileLight(element, parent, streamGroup, worldOffset) {
+    const position = vec3(element.position, `${element.id}.position`);
+    if (!/^#[0-9a-fA-F]{6}$/.test(element.color)) {
+        throw new Error(`${element.id}.color must be #RRGGBB`);
+    }
+    const luminousIntensityCandela = positive(element.luminousIntensityCandela, `${element.id}.luminousIntensityCandela`);
+    const rangeM = positive(element.rangeM, `${element.id}.rangeM`);
+    if (element.rotation !== undefined && element.rotationYDeg !== undefined) {
+        throw new Error(`${element.id} must use rotation or rotationYDeg, not both`);
+    }
+    const rotation = element.rotation !== undefined
+        ? quaternion(element.rotation, `${element.id}.rotation`)
+        : yawQuaternion(element.rotationYDeg ?? 0);
+    if (element.shadowMapSize !== undefined &&
+        ![256, 512, 1024, 2048].includes(element.shadowMapSize)) {
+        throw new Error(`${element.id}.shadowMapSize must be 256, 512, 1024, or 2048`);
+    }
+    if (element.kind === 'spot') {
+        finite(element.innerConeDeg, `${element.id}.innerConeDeg`);
+        finite(element.outerConeDeg, `${element.id}.outerConeDeg`);
+        if (element.innerConeDeg < 0 ||
+            element.outerConeDeg > 90 ||
+            element.innerConeDeg >= element.outerConeDeg) {
+            throw new Error(`${element.id} spot cones must satisfy 0 <= innerConeDeg < outerConeDeg <= 90`);
+        }
+    }
+    const nodeId = `node.${element.id}`;
+    const lightId = `light.${element.id}`;
+    const shadow = {
+        enabled: element.castShadow ?? false,
+        mapSize: element.shadowMapSize ?? 512,
+    };
+    const light = element.kind === 'point'
+        ? {
+            id: lightId,
+            node: nodeId,
+            type: 'point',
+            color: element.color,
+            luminousIntensityCandela,
+            rangeM,
+            shadow,
+            required: false,
+            fallback: { unsupported: 'unshadowed' },
+        }
+        : {
+            id: lightId,
+            node: nodeId,
+            type: 'spot',
+            color: element.color,
+            luminousIntensityCandela,
+            rangeM,
+            innerConeDeg: element.innerConeDeg,
+            outerConeDeg: element.outerConeDeg,
+            shadow,
+            required: false,
+            fallback: { unsupported: 'unshadowed' },
+        };
+    const worldPosition = addVec3(worldOffset, position);
+    return {
+        node: {
+            id: nodeId,
+            parent,
+            transform: { position, rotation, scale: [1, 1, 1] },
+            streamGroup,
+            components: [{ type: 'light.attachments', lights: [lightId] }],
+        },
+        light,
+        // A practical light must not enlarge a Space's portal activation volume by
+        // its illumination range. The containing architecture owns residency.
+        bounds: { min: worldPosition, max: [...worldPosition] },
+    };
+}
+function optionalRange(value, label, min, max) {
+    if (value === undefined)
+        return undefined;
+    finite(value, label);
+    if (value < min || value > max)
+        throw new Error(`${label} must be between ${min} and ${max}`);
+    return value;
+}
+function compileWater(element, parent, streamGroup, worldOffset) {
+    const position = vec3(element.position, `${element.id}.position`);
+    const size = vec3(element.size, `${element.id}.size`).map((part, axis) => positive(part, `${element.id}.size[${axis}]`));
+    const localBounds = {
+        min: size.map((part) => -part / 2),
+        max: size.map((part) => part / 2),
+    };
+    const surfaceHeight = finite(element.surfaceHeight ?? size[1] / 2, `${element.id}.surfaceHeight`);
+    if (surfaceHeight < localBounds.min[1] || surfaceHeight > localBounds.max[1]) {
+        throw new Error(`${element.id}.surfaceHeight must lie inside the volume's local Y bounds`);
+    }
+    const appearance = element.appearance;
+    if (appearance?.color !== undefined && !/^#[0-9a-fA-F]{6}$/.test(appearance.color)) {
+        throw new Error(`${element.id}.appearance.color must be #RRGGBB`);
+    }
+    optionalRange(appearance?.opacity, `${element.id}.appearance.opacity`, 0.05, 1);
+    optionalRange(appearance?.roughness, `${element.id}.appearance.roughness`, 0, 1);
+    optionalRange(appearance?.rippleScaleM, `${element.id}.appearance.rippleScaleM`, 0.05, 1000);
+    optionalRange(appearance?.rippleSpeedMps, `${element.id}.appearance.rippleSpeedMps`, 0, 20);
+    const swimming = element.swimming;
+    optionalRange(swimming?.entryDepthM, `${element.id}.swimming.entryDepthM`, 0.1, 5);
+    optionalRange(swimming?.exitDepthM, `${element.id}.swimming.exitDepthM`, 0, 5);
+    optionalRange(swimming?.floatDepthM, `${element.id}.swimming.floatDepthM`, 0.1, 5);
+    const rotation = yawQuaternion(element.rotationYDeg ?? 0);
+    return {
+        node: {
+            id: `node.${element.id}`,
+            parent,
+            transform: { position, rotation, scale: [1, 1, 1] },
+            streamGroup,
+            components: [{
+                    type: 'water.volume',
+                    shape: 'box',
+                    bounds: localBounds,
+                    surfaceHeight,
+                    ...(appearance ? { appearance } : {}),
+                    ...(swimming ? { swimming } : {}),
+                }],
+        },
+        bounds: translateBounds(rotatedBoxBounds(position, size, rotation), worldOffset),
+    };
+}
+function compileBuilding(building, rootNodeId, materials, version, ids) {
+    elementId(building.id, ids);
+    const children = version === 1 ? building.elements : building.children;
+    if (!children?.length) {
+        throw new Error(`building ${building.id} must contain at least one ${version === 1 ? 'element' : 'child'}`);
+    }
+    if (version === 1 && building.children !== undefined) {
+        throw new Error(`version 1 building ${building.id} must use elements, not children`);
+    }
+    if (version === 2 && building.elements !== undefined) {
+        throw new Error(`version 2 building ${building.id} must use children, not elements`);
+    }
+    const position = vec3(building.position ?? [0, 0, 0], `${building.id}.position`);
+    const groupId = `stream.${building.id}`;
+    const buildingNodeId = `node.${building.id}`;
+    const inherited = {
+        material: undefined,
+        collision: true,
+        role: 'exterior',
+        stream: { mode: 'distance', priority: 50 },
+    };
+    const properties = inheritProperties(building, inherited, { role: 'exterior' });
+    const buildingGroup = {
+        id: groupId,
+        mode: properties.stream.mode,
+        priority: properties.stream.priority,
+        dependency: 'stream.root',
+        nodes: [buildingNodeId],
+        bounds: null,
+        leafCount: 0,
+    };
+    const context = {
+        materials,
+        nodes: [],
+        leaves: [],
+        lights: [],
+        waterCount: 0,
+        groups: [buildingGroup],
+        ids,
+    };
+    context.nodes.push({
+        id: buildingNodeId,
+        parent: rootNodeId,
+        transform: { position, rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+        streamGroup: groupId,
+    });
+    const compileElement = (element, parentNodeId, activeGroup, inheritedProperties, worldOffset) => {
+        elementId(element.id, context.ids);
+        if (element.type === 'light') {
+            const compiledLight = compileLight(element, parentNodeId, activeGroup.id, worldOffset);
+            context.nodes.push(compiledLight.node);
+            context.lights.push(compiledLight.light);
+            activeGroup.nodes.push(compiledLight.node.id);
+            activeGroup.bounds = expandBounds(activeGroup.bounds, compiledLight.bounds);
+            activeGroup.leafCount += 1;
+            return compiledLight.bounds;
+        }
+        if (element.type === 'water') {
+            const compiledWater = compileWater(element, parentNodeId, activeGroup.id, worldOffset);
+            context.nodes.push(compiledWater.node);
+            activeGroup.nodes.push(compiledWater.node.id);
+            activeGroup.bounds = expandBounds(activeGroup.bounds, compiledWater.bounds);
+            activeGroup.leafCount += 1;
+            context.waterCount += 1;
+            return compiledWater.bounds;
+        }
+        if (element.type === 'wall' || element.type === 'floor' || element.type === 'ceiling' || element.type === 'primitive') {
+            const leaf = compileLeaf(element, parentNodeId, activeGroup.id, context.materials, inheritedProperties, worldOffset);
+            context.nodes.push(leaf.node);
+            context.leaves.push(leaf);
+            activeGroup.nodes.push(leaf.node.id);
+            activeGroup.bounds = expandBounds(activeGroup.bounds, leaf.bounds);
+            activeGroup.leafCount += 1;
+            return leaf.bounds;
+        }
+        const container = element;
+        if (container.children.length === 0) {
+            throw new Error(`${container.type} ${container.id} must contain at least one child`);
+        }
+        const defaultRole = container.type === 'space' ? 'interior' : undefined;
+        const resolvedRole = container.role ?? defaultRole ?? inheritedProperties.role;
+        const defaults = {
+            ...(defaultRole ? { role: defaultRole } : {}),
+            ...(resolvedRole === 'interior' ? { streamMode: 'portal' } : {}),
+        };
+        const containerProperties = inheritProperties(container, inheritedProperties, defaults);
+        const createsStreamBoundary = container.type === 'space' ||
+            container.role !== undefined ||
+            container.stream !== undefined ||
+            containerProperties.role !== inheritedProperties.role;
+        const localPosition = vec3(container.position ?? [0, 0, 0], `${container.id}.position`);
+        if (container.type === 'level') {
+            localPosition[1] += finite(container.elevation ?? 0, `${container.id}.elevation`);
+        }
+        const containerWorldOffset = addVec3(worldOffset, localPosition);
+        const containerNodeId = `node.${container.id}`;
+        let containerGroup = activeGroup;
+        if (createsStreamBoundary) {
+            containerGroup = {
+                id: `stream.${container.id}`,
+                mode: containerProperties.stream.mode,
+                priority: containerProperties.stream.priority,
+                dependency: activeGroup.id,
+                nodes: [],
+                bounds: null,
+                leafCount: 0,
+            };
+            context.groups.push(containerGroup);
+        }
+        containerGroup.nodes.push(containerNodeId);
+        context.nodes.push({
+            id: containerNodeId,
+            parent: parentNodeId,
+            transform: { position: localPosition, rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+            streamGroup: containerGroup.id,
+        });
+        const subtreeBounds = container.children.reduce((bounds, child) => expandBounds(bounds, compileElement(child, containerNodeId, containerGroup, containerProperties, containerWorldOffset)), null);
+        containerGroup.bounds = expandBounds(containerGroup.bounds, subtreeBounds);
+        activeGroup.bounds = expandBounds(activeGroup.bounds, subtreeBounds);
+        return subtreeBounds;
+    };
+    for (const child of children) {
+        buildingGroup.bounds = expandBounds(buildingGroup.bounds, compileElement(child, buildingNodeId, buildingGroup, properties, position));
+    }
+    const bounds = buildingGroup.bounds;
+    const groups = context.groups.map((group) => ({
+        id: group.id,
+        mode: group.mode,
+        priority: group.priority,
+        cells: [{
+                id: `cell.${group.id.slice('stream.'.length)}`,
+                bounds: group.bounds ?? bounds,
+                nodes: group.nodes,
+            }],
+        dependencies: [group.dependency],
+        estimatedMemoryMiB: Math.max(1, Math.ceil(group.leafCount / 256)),
+    }));
+    return { nodes: context.nodes, groups, bounds, leaves: context.leaves, lights: context.lights, waterCount: context.waterCount };
+}
+const MIB = 1024 * 1024;
+const SPLAT_MIME_TYPE = 'image/png';
+function terrainStrides(element) {
+    const strides = element.lod?.strideDistancesM;
+    if (strides === undefined)
+        return undefined;
+    if (!Array.isArray(strides) || strides.length !== 3) {
+        throw new Error(`terrain ${element.id}.lod.strideDistancesM must contain three distances`);
+    }
+    return strides.map((value, index) => positive(value, `terrain ${element.id}.lod.strideDistancesM[${index}]`));
+}
+/**
+ * Compiles a terrain source folder into nodes, per-tile streaming groups, bundle resources and the `scene.terrain`
+ * block. Node ids match the Continuum adapter's, so one authored terrain is named alike on both publish lanes.
+ */
+function compileTerrain(element, baseDir) {
+    if (element.type !== 'terrain')
+        throw new Error('terrain element must declare type "terrain"');
+    if (typeof element.source !== 'string' || !element.source.trim()) {
+        throw new Error(`terrain ${element.id}.source must name the folder holding terrain.json`);
+    }
+    const dir = (0, node_path_1.resolve)(baseDir ?? process.cwd(), element.source);
+    const index = (0, source_1.readTerrainSourceIndex)(dir);
+    if (!index.material) {
+        throw new Error(`terrain ${element.id}: "${dir}" carries no baked material — run \`helix terrain bake\` on it first`);
+    }
+    const tileMetres = (index.grid.tileSamples - 1) * index.grid.metresPerSample;
+    const bundleFiles = [];
+    const resources = [];
+    const nodes = [];
+    const groups = [];
+    const tiles = [];
+    // One digest is one bundle resource: flat ground bakes the SAME splat for many tiles, and a second
+    // resource over those bytes would declare one bundle assetId under two URIs, which the document rejects.
+    const resourceByDigest = new Map();
+    const bundleResource = (resourceId, file, heights) => {
+        const shared = resourceByDigest.get(file.sha256);
+        if (shared)
+            return shared;
+        resourceByDigest.set(file.sha256, resourceId);
+        bundleFiles.push({ uri: `terrain/${file.path}`, path: (0, node_path_1.join)(dir, file.path), bytes: file.bytes, sha256: file.sha256 });
+        resources.push({
+            id: resourceId,
+            kind: heights ? 'terrain' : 'texture',
+            source: { kind: 'bundle', assetId: `terrain:${file.sha256}`, uri: `terrain/${file.path}` },
+            integrity: { sha256: file.sha256 },
+            bytes: file.bytes,
+            mimeType: heights ? helix_manifest_1.HEIGHTFIELD_MIME_TYPE : SPLAT_MIME_TYPE,
+            required: true,
+        });
+        return resourceId;
+    };
+    const layerMiB = (layer) => Math.max(1, Math.ceil((layer.heights.bytes + (layer.splat?.bytes ?? 0) + (layer.normals?.bytes ?? 0)) / MIB));
+    const coarseNodeId = `terrain.${element.id}.coarse`;
+    const coarseHeights = bundleResource(`resource.${coarseNodeId}.heights`, index.coarse.heights, true);
+    const coarseSplat = index.coarse.splat ? bundleResource(`resource.${coarseNodeId}.splat`, index.coarse.splat, false) : null;
+    const coarseNormals = index.coarse.normals ? bundleResource(`resource.${coarseNodeId}.normals`, index.coarse.normals, false) : null;
+    nodes.push({
+        id: coarseNodeId,
+        resource: coarseHeights,
+        transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+        streamGroup: 'stream.root',
+    });
+    let heightMin = Infinity;
+    let heightMax = -Infinity;
+    for (const tile of index.tiles) {
+        const nodeId = `terrain.${element.id}.tile.${tile.tx}.${tile.tz}`;
+        const heights = bundleResource(`resource.${nodeId}.heights`, tile.heights, true);
+        const splat = tile.splat ? bundleResource(`resource.${nodeId}.splat`, tile.splat, false) : null;
+        const normals = tile.normals ? bundleResource(`resource.${nodeId}.normals`, tile.normals, false) : null;
+        const minX = index.grid.originX + tile.tx * tileMetres;
+        const minZ = index.grid.originZ + tile.tz * tileMetres;
+        heightMin = Math.min(heightMin, tile.heightMin);
+        heightMax = Math.max(heightMax, tile.heightMax);
+        nodes.push({
+            id: nodeId,
+            resource: heights,
+            transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+            streamGroup: `stream.${nodeId}`,
+        });
+        groups.push({
+            id: `stream.${nodeId}`,
+            mode: 'distance',
+            priority: 60,
+            cells: [{
+                    id: `cell.${nodeId}`,
+                    // Flat terrain still needs a non-degenerate streaming volume; height samples and colliders stay unchanged.
+                    bounds: { min: [minX, tile.heightMin, minZ], max: [minX + tileMetres, Math.max(tile.heightMax, tile.heightMin + 0.01), minZ + tileMetres] },
+                    nodes: [nodeId],
+                }],
+            dependencies: ['stream.root'],
+            estimatedMemoryMiB: layerMiB(tile),
+        });
+        tiles.push({
+            tx: tile.tx,
+            tz: tile.tz,
+            node: nodeId,
+            heights,
+            ...(splat ? { splat } : {}),
+            ...(normals ? { normals } : {}),
+            ...(tile.layers ? { layers: [...tile.layers] } : {}),
+            heightMin: tile.heightMin,
+            heightMax: tile.heightMax,
+        });
+    }
+    const strides = terrainStrides(element);
+    return {
+        nodes,
+        groups,
+        resources,
+        bundleFiles,
+        coarseNodeId,
+        coarseMemoryMiB: layerMiB(index.coarse),
+        bounds: {
+            min: [index.grid.originX, heightMin, index.grid.originZ],
+            max: [
+                index.grid.originX + index.grid.tilesX * tileMetres,
+                heightMax,
+                index.grid.originZ + index.grid.tilesZ * tileMetres,
+            ],
+        },
+        terrain: {
+            kind: 'heightfield',
+            node: coarseNodeId,
+            resource: coarseHeights,
+            grid: { ...index.grid },
+            tiles,
+            coarse: {
+                metresPerSample: index.coarse.metresPerSample,
+                ...(coarseSplat ? { splat: coarseSplat } : {}),
+                ...(coarseNormals ? { normals: coarseNormals } : {}),
+                ...(index.coarse.layers ? { layers: [...index.coarse.layers] } : {}),
+                heightMin: index.coarse.heightMin,
+                heightMax: index.coarse.heightMax,
+            },
+            material: index.material,
+            ...(strides ? { lod: { strideDistancesM: strides } } : {}),
+            ...(element.colliderRadiusM !== undefined
+                ? { colliderRadiusM: positive(element.colliderRadiusM, `terrain ${element.id}.colliderRadiusM`) }
+                : {}),
+        },
+    };
+}
+const GLB_MIME_TYPE = 'model/gltf-binary';
+const KTX2_MIME_TYPE = 'image/ktx2';
+/** Flat road cells bake zero-height bounds, and a streaming volume must be a real box on every axis. */
+const MIN_CELL_EXTENT_M = 0.01;
+/** The collider answers for whatever stands on the cell, so its activation volume is taller than the baked triangles. */
+const COLLIDER_CELL_PAD_M = 2;
+const SCENE_ID = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const BUNDLE_URI = /^[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
+/** `meshcells:<element>:<kind>:<64 hex>` must stay inside the 128-character bundle assetId cap. */
+const MESH_CELLS_ID_LENGTH = 32;
+function meshCellBounds(bounds, padY = 0) {
+    const min = [bounds.min[0], bounds.min[1] - padY, bounds.min[2]];
+    const max = [bounds.max[0], bounds.max[1] + padY, bounds.max[2]];
+    return { min, max: max.map((value, axis) => Math.max(value, min[axis] + MIN_CELL_EXTENT_M)) };
+}
+/**
+ * Compiles a baked mesh-cell folder into one eager render group of per-cell model nodes plus, per collision cell, a
+ * distance group whose render-less carrier node owns that cell's triangle-mesh collision set.
+ */
+function compileMeshCells(element, baseDir) {
+    if (element.type !== 'meshCells')
+        throw new Error('mesh cells element must declare type "meshCells"');
+    if (typeof element.id !== 'string' || !SCENE_ID.test(element.id) || element.id.length > MESH_CELLS_ID_LENGTH) {
+        throw new Error(`meshCells "${element.id}": id must be a lowercase Scene id of at most ${MESH_CELLS_ID_LENGTH} characters`);
+    }
+    if (typeof element.source !== 'string' || !BUNDLE_URI.test(element.source)) {
+        throw new Error(`meshCells ${element.id}.source must name a folder beside the document, without "." or ".." segments`);
+    }
+    const priority = element.priority ?? 60;
+    if (!Number.isInteger(priority) || priority < 0 || priority > 1000) {
+        throw new Error(`meshCells ${element.id}.priority must be an integer between 0 and 1000`);
+    }
+    for (const flag of ['collision', 'giContribute']) {
+        if (element[flag] !== undefined && typeof element[flag] !== 'boolean')
+            throw new Error(`meshCells ${element.id}.${flag} must be a boolean`);
+    }
+    const index = (0, meshCells_1.readMeshCellsIndex)((0, node_path_1.resolve)(baseDir ?? process.cwd(), element.source), element.variants);
+    // The element's override wins over the folder's baked intent; only a refusal is written, so `true` stays the default.
+    const giContribute = element.giContribute ?? index.giContribute;
+    const renderMesh = () => [
+        { type: 'render.mesh', castShadow: true, receiveShadow: true, ...(giContribute === false ? { giContribute: false } : {}) },
+    ];
+    const resources = [];
+    const bundleFiles = [];
+    const nodes = [];
+    const groups = [];
+    const collisionSets = [];
+    const identity = () => ({ position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] });
+    // One digest is one bundle resource per kind: repeated cells (empty tiles, a shared collider) ship their bytes once,
+    // and the kind keeps a render GLB and a byte-identical collider GLB from claiming one assetId under two URIs.
+    const resourceByDigest = new Map();
+    const bundleResource = (resourceId, kind, file) => {
+        const key = `${kind}\0${file.sha256}`;
+        const shared = resourceByDigest.get(key);
+        if (shared)
+            return shared;
+        const uri = `${element.source}/${file.file.split('\\').join('/')}`;
+        if (!BUNDLE_URI.test(uri))
+            throw new Error(`meshCells ${element.id}: "${file.file}" is not a canonical bundle path`);
+        resourceByDigest.set(key, resourceId);
+        bundleFiles.push({ uri, path: (0, node_path_1.join)(index.dir, file.file), bytes: file.bytes, sha256: file.sha256 });
+        resources.push({
+            id: resourceId,
+            kind,
+            source: { kind: 'bundle', assetId: `meshcells:${element.id}:${kind}:${file.sha256}`, uri },
+            integrity: { sha256: file.sha256 },
+            bytes: file.bytes,
+            mimeType: kind === 'texture' ? KTX2_MIME_TYPE : GLB_MIME_TYPE,
+            required: true,
+        });
+        return resourceId;
+    };
+    index.textures.forEach((texture, position) => bundleResource(`${element.id}.t.${position}`, 'texture', texture));
+    const cellById = new Map();
+    let bounds = null;
+    for (const cell of index.render) {
+        const nodeId = `${element.id}.r.${cell.cx}.${cell.cz}`;
+        const cellBounds = meshCellBounds(cell.bounds);
+        nodes.push({
+            id: nodeId,
+            resource: bundleResource(`${element.id}.rm.${cell.cx}.${cell.cz}`, 'model', cell),
+            transform: identity(),
+            streamGroup: `${element.id}.far`,
+            components: renderMesh(),
+        });
+        cellById.set(`${cell.cx}.${cell.cz}`, { id: `${element.id}.rc.${cell.cx}.${cell.cz}`, bounds: cellBounds, nodes: [nodeId] });
+        bounds = expandBounds(bounds, cellBounds);
+    }
+    for (const variant of index.selectedVariants) {
+        if (!SCENE_ID.test(variant.key))
+            throw new Error(`meshCells ${element.id}: variant family "${variant.key}" is not a Scene id`);
+        for (const cell of variant.cells) {
+            const streamCell = cellById.get(`${cell.cx}.${cell.cz}`);
+            if (!streamCell)
+                throw new Error(`meshCells ${element.id}: variant "${variant.key}" cell ${cell.cx}.${cell.cz} has no render cell to join`);
+            const nodeId = `${element.id}.v.${variant.key}.${cell.cx}.${cell.cz}`;
+            nodes.push({
+                id: nodeId,
+                resource: bundleResource(`${element.id}.vm.${variant.key}.${cell.cx}.${cell.cz}`, 'model', cell),
+                transform: identity(),
+                streamGroup: `${element.id}.far`,
+                components: renderMesh(),
+            });
+            streamCell.nodes.push(nodeId);
+            streamCell.bounds = expandBounds(streamCell.bounds, meshCellBounds(cell.bounds));
+            bounds = expandBounds(bounds, streamCell.bounds);
+        }
+    }
+    const eagerBytes = [...index.render, ...index.selectedVariants.flatMap((variant) => variant.cells), ...index.textures]
+        .reduce((total, file) => total + file.bytes, 0);
+    groups.push({
+        id: `${element.id}.far`,
+        mode: 'eager',
+        priority: 100,
+        cells: [...cellById.values()],
+        dependencies: ['stream.root'],
+        estimatedMemoryMiB: Math.max(1, Math.ceil(eagerBytes / MIB)),
+    });
+    if (element.collision !== false) {
+        for (const cell of index.collision) {
+            const suffix = `${cell.cx}.${cell.cz}`;
+            const nodeId = `${element.id}.cn.${suffix}`;
+            const setId = `${element.id}.cs.${suffix}`;
+            // The carrier renders nothing: it exists to own the set, and a node without a resource is the smallest legal shape.
+            nodes.push({
+                id: nodeId,
+                transform: identity(),
+                streamGroup: `${element.id}.c.${suffix}`,
+                components: [{ type: 'collision.proxy-set', set: setId }],
+            });
+            groups.push({
+                id: `${element.id}.c.${suffix}`,
+                mode: 'distance',
+                priority,
+                cells: [{ id: `${element.id}.cc.${suffix}`, bounds: meshCellBounds(cell.bounds, COLLIDER_CELL_PAD_M), nodes: [nodeId] }],
+                dependencies: ['stream.root'],
+                estimatedMemoryMiB: Math.max(1, Math.ceil(cell.bytes / MIB)),
+            });
+            collisionSets.push({
+                id: setId,
+                node: nodeId,
+                static: [{
+                        id: `${element.id}.co.${suffix}`,
+                        shape: 'triangle-mesh',
+                        resource: bundleResource(`${element.id}.cr.${suffix}`, 'collider', cell),
+                        transform: identity(),
+                    }],
+            });
+            bounds = expandBounds(bounds, meshCellBounds(cell.bounds));
+        }
+    }
+    return { nodes, groups, resources, collisionSets, bundleFiles, bounds: bounds };
+}
+function compileSceneElementsBundle(input, options = {}) {
+    if (input.format !== 'helix.scene-elements' || (input.version !== 1 && input.version !== 2)) {
+        throw new Error('semantic input must be helix.scene-elements version 1 or 2');
+    }
+    id(input.id, 'scene id');
+    if (!input.title.trim())
+        throw new Error('scene title is required');
+    if (input.buildings.length === 0 && !input.terrain && !input.placements && !input.meshCells?.length) {
+        throw new Error('at least one building, terrain, placements region or mesh-cell folder is required');
+    }
+    const rootNodeId = 'node.root';
+    const sunNodeId = 'node.sun';
+    const compiledMaterials = compileMaterials(input.materials);
+    const semanticIds = new Set();
+    if (input.terrain)
+        elementId(input.terrain.id, semanticIds);
+    const terrain = input.terrain ? compileTerrain(input.terrain, options.baseDir) : null;
+    if (input.meshCells !== undefined && !Array.isArray(input.meshCells))
+        throw new Error('meshCells must be an array of baked cell folders');
+    const meshCells = (input.meshCells ?? []).map((element) => {
+        elementId(element.id, semanticIds);
+        return compileMeshCells(element, options.baseDir);
+    });
+    const placements = input.placements ? (0, source_2.placementsBundle)((0, node_path_1.resolve)(options.baseDir ?? process.cwd(), input.placements.source)) : null;
+    const compiled = input.buildings.map((building) => compileBuilding(building, rootNodeId, compiledMaterials, input.version, semanticIds));
+    const builtBounds = compiled.reduce((bounds, building) => expandBounds(bounds, building.bounds), null);
+    let placementBounds = terrain ? expandBounds(builtBounds, terrain.bounds) : builtBounds;
+    for (const element of meshCells)
+        placementBounds = expandBounds(placementBounds, element.bounds);
+    for (const region of placements?.placements.regions ?? [])
+        placementBounds = expandBounds(placementBounds, region.bounds);
+    if (!placementBounds)
+        throw new Error('scene has no bounds; add terrain, a building or a populated placements region');
+    const nodes = [
+        {
+            id: rootNodeId,
+            transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+            streamGroup: 'stream.root',
+        },
+        {
+            id: sunNodeId,
+            parent: rootNodeId,
+            transform: { position: [0, 0, 0], rotation: [-0.4030582, 0.272532008, 0.127083762, 0.864361099], scale: [1, 1, 1] },
+            streamGroup: 'stream.root',
+            components: [{ type: 'light.attachments', lights: ['light.sun'] }],
+        },
+        ...(terrain ? terrain.nodes : []),
+        ...meshCells.flatMap((element) => element.nodes),
+        ...compiled.flatMap((building) => building.nodes),
+    ];
+    const devices = (0, devices_1.compileSceneDevices)(input.version === 2 ? input.devices : undefined, nodes, options.baseDir ?? process.cwd());
+    const spawnPosition = vec3(input.spawn.position, 'spawn.position');
+    const scene = {
+        format: 'helix.scene',
+        version: 2,
+        id: input.id,
+        revision: '0'.repeat(16),
+        integrity: { sha256: '0'.repeat(64) },
+        title: input.title,
+        units: 'meters',
+        coordinateSystem: { handedness: 'right', up: '+Y', forward: '-Z' },
+        profiles: {
+            world: {
+                scene: 'scene.root',
+                kind: 'world',
+                persistence: 'session',
+                maxPlayers: 32,
+                overrideAuthority: 'none',
+                runtimePolicy: {
+                    memoryBudgetMiB: input.runtimePolicy?.memoryBudgetMiB ?? 64,
+                    streamRadiusM: input.runtimePolicy?.streamRadiusM ?? 160,
+                    allowSurfaceOverrides: false,
+                    allowItemPlacement: false,
+                },
+            },
+        },
+        scenes: [{
+                id: 'scene.root',
+                nodes: nodes.map((node) => node.id),
+                streamGroups: [
+                    'stream.root',
+                    ...(terrain ? terrain.groups.map((group) => group.id) : []),
+                    ...meshCells.flatMap((element) => element.groups.map((group) => group.id)),
+                    ...compiled.flatMap((building) => building.groups.map((group) => group.id)),
+                ],
+            }],
+        resources: [...(terrain ? terrain.resources : []), ...meshCells.flatMap((element) => element.resources),
+            ...(placements ? placements.resources : [])],
+        nodes,
+        itemDefinitions: devices.definitions,
+        itemInstances: devices.instances,
+        ...(devices.deviceLinks.length ? { deviceLinks: devices.deviceLinks } : {}),
+        terrain: terrain ? terrain.terrain : { kind: 'none' },
+        ...(placements ? { placements: placements.placements } : {}),
+        environment: { background: true, intensityScale: 1, rotationYDeg: 0, exposureEV100: 0, fallbackColor: '#9db4c8', required: false },
+        lights: [{
+                id: 'light.sun',
+                node: sunNodeId,
+                type: 'directional',
+                color: '#fff4e0',
+                illuminanceLux: 2.4,
+                shadow: { enabled: true, mapSize: 1024 },
+                required: false,
+                fallback: { unsupported: 'unshadowed' },
+            }, ...compiled.flatMap((building) => building.lights)],
+        spawns: [{ id: 'spawn.main', position: spawnPosition, rotation: yawQuaternion(input.spawn.rotationYDeg ?? 0), profileAccess: ['world'], clearanceRadiusM: 0.45, clearanceHeightM: 1.9 }],
+        collision: { sets: [...meshCells.flatMap((element) => element.collisionSets),
+                ...compiled.flatMap((building) => building.leaves.map((leaf) => leaf.collisionSet).filter((set) => set !== null))] },
+        navigation: { walkableSurfaces: compiled.flatMap((building) => building.leaves.filter((leaf) => leaf.surface.slot === 'floor').map((leaf) => leaf.surface.id)), agent: { radiusM: 0.35, heightM: 1.8, stepHeightM: 0.32, maxSlopeDeg: 48 }, navmesh: null, fallback: 'physics-walkability' },
+        placement: { bounds: placementBounds, maxItemInstances: devices.instances.length, snapGridM: 0.05, allowedProfiles: [] },
+        surfaces: compiled.flatMap((building) => building.leaves.map((leaf) => leaf.surface)),
+        // ADR-0004 P6: no Scene-level materials[] any more — every named `ref`
+        // resolves to its inline fallback color at compile time (see
+        // compileMaterials/resolveMaterial above).
+        materials: [],
+        behaviors: [],
+        streamGroups: [
+            {
+                id: 'stream.root',
+                mode: 'eager',
+                priority: 100,
+                cells: [{ id: 'cell.root', bounds: placementBounds, nodes: [rootNodeId, sunNodeId, ...(terrain ? [terrain.coarseNodeId] : [])] }],
+                dependencies: [],
+                // The coarse layer is decoded at boot, so the eager group commits its bytes.
+                estimatedMemoryMiB: 1 + (terrain ? terrain.coarseMemoryMiB : 0),
+            },
+            ...(terrain ? terrain.groups : []),
+            ...meshCells.flatMap((element) => element.groups),
+            ...compiled.flatMap((building) => building.groups),
+        ],
+        capabilities: {
+            required: ['render.primitive/1', 'lighting.punctual/1', ...(terrain ? [helix_manifest_1.HELIX_SCENE_TERRAIN_CAPABILITY] : []),
+                ...(compiled.some((building) => building.waterCount > 0) ? [helix_manifest_1.HELIX_SCENE_WATER_CAPABILITY] : []),
+                ...(meshCells.length ? ['render.mesh/1'] : []), ...(placements ? [helix_manifest_1.PLACEMENTS_CAPABILITY] : []),
+                ...(placements?.placements.distant ? [helix_manifest_1.PLACEMENTS_DISTANT_CAPABILITY] : []),
+                ...(devices.definitions.length || devices.deviceLinks.length ? [helix_manifest_1.HELIX_SCENE_DEVICE_CAPABILITY] : [])],
+            optional: [],
+        },
+        runtimeExtensions: [],
+        adapters: { unreal: helix_manifest_1.HELIX_TO_UNREAL_ADAPTER },
+    };
+    scene.revision = (0, helix_manifest_1.computeSceneDocumentIntegrity)(scene).slice(0, 16);
+    scene.integrity.sha256 = (0, helix_manifest_1.computeSceneDocumentIntegrity)(scene);
+    const validation = (0, helix_manifest_1.validateSceneDocument)(scene);
+    if (!validation.valid)
+        throw new Error(`compiled Scene v2 is invalid: ${validation.errors.join('; ')}`);
+    return {
+        scene: validation.scene,
+        bundleFiles: [...(terrain ? terrain.bundleFiles : []), ...meshCells.flatMap((element) => element.bundleFiles),
+            ...(placements ? placements.bundleFiles : [])],
+    };
+}
+/** The sealed document alone, for callers that ship no bundle bytes beside it. */
+function compileSceneElements(input, options = {}) {
+    return compileSceneElementsBundle(input, options).scene;
+}
+//# sourceMappingURL=compiler.js.map