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

package/dist/sceneImport/package.js

@@ -0,0 +1,1004 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCENE_V2_RESOURCE_MAX_FILES = exports.SCENE_V2_RESOURCE_MAX_BYTES = exports.SCENE_V2_PACKAGE_MAX_BYTES = void 0;
+exports.createSceneV2Package = createSceneV2Package;
+exports.assertStagedPackageMembers = assertStagedPackageMembers;
+exports.assertEmptySceneOutput = assertEmptySceneOutput;
+exports.createSceneV2MultiAssetPackage = createSceneV2MultiAssetPackage;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const proxy_1 = require("./proxy");
+const types_1 = require("./types");
+const streamLayout_1 = require("./streamLayout");
+const gltfIo_1 = require("./gltfIo");
+const externalTextures_1 = require("./externalTextures");
+/**
+ * The World-build endpoint's multipart limits, taken from the shared contract
+ * rather than re-typed here: a package can sit under the aggregate cap and
+ * still be refused for a single oversized resource, so both are checked before
+ * anything is uploaded, and a copied number would let the CLI reject packages
+ * the server accepts (or worse, the reverse).
+ */
+exports.SCENE_V2_PACKAGE_MAX_BYTES = helix_manifest_1.BUNDLE_MAX_TOTAL_BYTES;
+exports.SCENE_V2_RESOURCE_MAX_BYTES = helix_manifest_1.BUNDLE_MAX_FILE_BYTES;
+/** One member of the bundle is the scene document itself; the rest are resources. */
+exports.SCENE_V2_RESOURCE_MAX_FILES = helix_manifest_1.BUNDLE_MAX_FILES - 1;
+async function createSceneV2Package(input) {
+    (0, types_1.assertFiniteVec3)(input.bounds.min, 'scene bounds min');
+    (0, types_1.assertFiniteVec3)(input.bounds.max, 'scene bounds max');
+    assertSourceReceipt(input.receipt);
+    if (input.bounds.min.some((value, axis) => value > input.bounds.max[axis])) {
+        throw new Error('scene bounds min must not exceed max');
+    }
+    if (input.proxy)
+        assertArtifact(input.proxy, 'proxy');
+    assertArtifact(input.detail, 'detail');
+    const totalBytes = (input.proxy?.bytes.length ?? 0) + input.detail.bytes.length;
+    if (totalBytes >= exports.SCENE_V2_PACKAGE_MAX_BYTES) {
+        throw new Error(`Scene v2 package is ${totalBytes} bytes; current build cap is ${exports.SCENE_V2_PACKAGE_MAX_BYTES}`);
+    }
+    const stable = (0, node_crypto_1.createHash)('sha256')
+        .update(input.sourceId)
+        .update(input.proxy?.contentSha256 ?? 'no-proxy')
+        .update(input.detail.contentSha256)
+        .digest('hex');
+    const sceneId = `scene.import.${stable.slice(0, 20)}`;
+    const rootId = `scene.root.${stable.slice(0, 12)}`;
+    const nodeId = `node.source.${stable.slice(0, 12)}`;
+    const groupId = `stream.source.${stable.slice(0, 12)}`;
+    const cellId = `cell.source.${stable.slice(0, 12)}`;
+    const detailResource = `resource.detail.${stable.slice(0, 12)}`;
+    const proxyResource = `resource.proxy.${stable.slice(0, 12)}`;
+    const colliderResource = `resource.collider.${stable.slice(0, 12)}`;
+    const collisionSetId = `collision.proxy.${stable.slice(0, 12)}`;
+    const colliderId = `collider.proxy.${stable.slice(0, 12)}`;
+    const sunNodeId = `node.sun.${stable.slice(0, 12)}`;
+    const sunId = `light.sun.${stable.slice(0, 12)}`;
+    const spawnProbe = (input.proxy ?? input.detail).spawn;
+    const spawnPosition = spawnProbe
+        ? spawnProbe.position
+        : [
+            (input.bounds.min[0] + input.bounds.max[0]) / 2,
+            input.bounds.max[1] + 1.9,
+            (input.bounds.min[2] + input.bounds.max[2]) / 2,
+        ];
+    const detailPath = `assets/${(0, node_path_1.basename)(input.detail.filename)}`;
+    // With no proxy, the collider stands on the detail GLB. A collider resource
+    // pointing at a dropped file would dangle, and silently omitting collision
+    // would drop the player through the world.
+    const colliderPath = input.proxy ? `assets/${(0, node_path_1.basename)(input.proxy.filename)}` : detailPath;
+    const maxAbs = Math.max(...input.bounds.min.map(Math.abs), ...input.bounds.max.map(Math.abs));
+    // LOD distance is measured from the NODE ORIGIN, not from the geometry the
+    // node carries. A whole imported sheet hangs off one node whose origin is a
+    // corner of the source cell, so a player standing in the middle of a 250 m
+    // sheet is ~180 m from that origin and a naive 100 m detail range hands them
+    // the blurred proxy while they are standing on the detailed street. Size the
+    // detail range to the cell's own extent so the detail LOD covers everything
+    // this node actually represents, and let the proxy serve the approach from
+    // outside it.
+    const cornerDistanceM = Math.hypot(Math.max(Math.abs(input.bounds.min[0]), Math.abs(input.bounds.max[0])), Math.max(Math.abs(input.bounds.min[1]), Math.abs(input.bounds.max[1])), Math.max(Math.abs(input.bounds.min[2]), Math.abs(input.bounds.max[2])));
+    const detailMaxDistanceM = Math.ceil(cornerDistanceM) + 32;
+    const estimatedMemoryMiB = Math.max(1, Math.ceil(totalBytes / (1024 * 1024)));
+    const scene = {
+        format: 'helix.scene',
+        version: 2,
+        id: sceneId,
+        revision: '0'.repeat(16),
+        integrity: { sha256: '0'.repeat(64) },
+        title: input.title,
+        units: 'meters',
+        coordinateSystem: { handedness: 'right', up: '+Y', forward: '-Z' },
+        profiles: {
+            world: {
+                scene: rootId,
+                kind: 'world',
+                persistence: 'session',
+                maxPlayers: 1,
+                overrideAuthority: 'none',
+                runtimePolicy: {
+                    memoryBudgetMiB: Math.max(64, estimatedMemoryMiB * 3),
+                    streamRadiusM: Math.max(32, detailMaxDistanceM),
+                    allowSurfaceOverrides: false,
+                    allowItemPlacement: false,
+                },
+            },
+        },
+        scenes: [{ id: rootId, nodes: [nodeId, sunNodeId], streamGroups: [groupId] }],
+        resources: [
+            resource(detailResource, detailPath, input.detail),
+            ...(input.proxy ? [resource(proxyResource, colliderPath, input.proxy)] : []),
+            resource(colliderResource, colliderPath, input.proxy ?? input.detail, 'collider'),
+        ],
+        nodes: [
+            {
+                id: nodeId,
+                resource: detailResource,
+                transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+                streamGroup: groupId,
+                // One real level beats two identical ones: with no proxy the node
+                // declares `only-available`, which the schema requires to carry exactly
+                // one level and the web runtime resolves to that level directly.
+                lod: input.proxy
+                    ? {
+                        selection: 'distance',
+                        levels: [
+                            { level: 0, resource: detailResource, maxDistanceM: detailMaxDistanceM },
+                            { level: 1, resource: proxyResource },
+                        ],
+                    }
+                    : { selection: 'only-available', levels: [{ level: 0, resource: detailResource }] },
+                components: [
+                    { type: 'render.mesh', castShadow: true, receiveShadow: true },
+                    { type: 'collision.proxy-set', set: collisionSetId },
+                ],
+            },
+            {
+                // An empty anchor whose local -Z is the sun direction: ~50 degrees of
+                // elevation off the +X/+Z side. Lights are attached to nodes, and a
+                // light with no node anchor is silently dropped by the web runtime.
+                id: sunNodeId,
+                transform: {
+                    position: [0, 0, 0],
+                    rotation: [-0.4030582, 0.272532008, 0.127083762, 0.864361099],
+                    scale: [1, 1, 1],
+                },
+                streamGroup: groupId,
+                components: [{ type: 'light.attachments', lights: [sunId] }],
+            },
+        ],
+        itemDefinitions: [],
+        itemInstances: [],
+        terrain: { kind: 'none' },
+        environment: {
+            background: true,
+            intensityScale: 1,
+            rotationYDeg: 0,
+            exposureEV100: 0,
+            fallbackColor: '#8aa4b8',
+            required: false,
+        },
+        lights: [
+            {
+                id: sunId,
+                node: sunNodeId,
+                type: 'directional',
+                color: '#fff4e0',
+                // Named lux by the schema, but the web runtime hands this straight to
+                // THREE.DirectionalLight.intensity, which is not in physical units —
+                // the shipped Home preset keys at 2.6. Match the reference
+                // implementation, not the field name.
+                illuminanceLux: 2.4,
+                // Photogrammetry and authored source art already carry their own baked
+                // shadowing, and a single ortho shadow map cannot usefully cover a
+                // kilometre-scale sheet, so a cast shadow here only double-darkens.
+                shadow: { enabled: false, mapSize: 1024 },
+                required: false,
+                fallback: { unsupported: 'unshadowed' },
+            },
+        ],
+        spawns: [
+            {
+                id: 'spawn.main',
+                // The proxy is what backs collision, so the spawn must be probed
+                // against the SAME geometry the capsule will stand on. Probing the
+                // detail mesh could place a player below the surface they collide with.
+                position: spawnPosition,
+                rotation: [0, 0, 0, 1],
+                profileAccess: ['world'],
+                clearanceRadiusM: 0.45,
+                clearanceHeightM: 1.9,
+            },
+        ],
+        collision: {
+            sets: [
+                {
+                    id: collisionSetId,
+                    node: nodeId,
+                    static: [
+                        {
+                            id: colliderId,
+                            shape: 'triangle-mesh',
+                            resource: colliderResource,
+                            transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+                        },
+                    ],
+                },
+            ],
+        },
+        navigation: {
+            walkableSurfaces: [],
+            agent: { radiusM: 0.35, heightM: 1.8, stepHeightM: 0.32, maxSlopeDeg: 48 },
+            navmesh: null,
+            fallback: 'physics-walkability',
+        },
+        placement: {
+            bounds: input.bounds,
+            maxItemInstances: 0,
+            snapGridM: 0.05,
+            allowedProfiles: [],
+        },
+        surfaces: [],
+        materials: [],
+        behaviors: [],
+        streamGroups: [
+            {
+                id: groupId,
+                mode: 'eager',
+                priority: 100,
+                cells: [{ id: cellId, bounds: input.bounds, nodes: [nodeId, sunNodeId] }],
+                dependencies: [],
+                estimatedMemoryMiB,
+            },
+        ],
+        capabilities: { required: ['render.mesh/1'], optional: [] },
+        runtimeExtensions: [
+            {
+                // Without this the web runtime adds NO ambient or hemisphere term, so a
+                // scene lit by one directional light renders every surface facing away
+                // from it at pure black. Imported source art is graded for daylight, so
+                // the sky/ground gradient carries most of the exposure and the sun only
+                // supplies direction.
+                id: 'ext.web.three-renderer',
+                extension: 'web.three-renderer/1',
+                runtime: 'web',
+                targetNodes: [sunNodeId],
+                required: false,
+                fallback: 'portable',
+                parameters: {
+                    // Three's MeshStandardMaterial divides incoming irradiance by PI, so
+                    // a surface only reads at its authored albedo when the ambient and
+                    // hemisphere terms sum to roughly PI. Source art imported this way is
+                    // photogrammetry or pre-graded interiors that already carry their own
+                    // baked shading, so nearly all of the exposure belongs in those flat
+                    // terms and the sun only supplies direction. Tuned against the live
+                    // Helsinki sheet: at 0.35/1.1 the streets and tree canopies rendered
+                    // near-black.
+                    ambientColor: '#ccd9e8',
+                    ambientIntensity: 2.0,
+                    hemisphereSkyColor: '#bcd8f5',
+                    hemisphereGroundColor: '#7d766a',
+                    hemisphereIntensity: 1.6,
+                    pointDecay: 2,
+                    directionalShadowExtent: 60,
+                    directionalShadowNear: 0.5,
+                    directionalShadowFar: 400,
+                },
+            },
+        ],
+        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(`generated Scene v2 is invalid: ${validation.errors.join('; ')}`);
+    }
+    const sceneJson = (0, types_1.serializeSceneDocument)(validation.scene);
+    const packageBytes = totalBytes + Buffer.byteLength(sceneJson);
+    if (packageBytes > exports.SCENE_V2_PACKAGE_MAX_BYTES) {
+        throw new Error(`generated Scene package exceeds the ${exports.SCENE_V2_PACKAGE_MAX_BYTES}-byte build cap`);
+    }
+    const receiptJson = `${JSON.stringify({
+        ...input.receipt,
+        rights: { ...input.receipt.rights },
+        outputs: {
+            proxy: input.proxy ? artifactReceipt(input.proxy, colliderPath) : null,
+            detail: artifactReceipt(input.detail, detailPath),
+            scene: {
+                id: scene.id,
+                revision: scene.revision,
+                integritySha256: scene.integrity.sha256,
+            },
+        },
+        spawn: {
+            position: spawnPosition,
+            groundProbe: spawnProbe
+                ? {
+                    source: 'proxy-geometry',
+                    groundY: spawnProbe.groundY,
+                    rejectedCandidates: spawnProbe.rejectedCandidates,
+                }
+                : {
+                    source: 'bounds-fallback',
+                    groundY: input.bounds.max[1],
+                    rejectedCandidates: 0,
+                },
+        },
+        unsupportedCapabilities: ['nested-scenes', 'scene-shards'],
+    }, null, 2)}\n`;
+    // A Scene package is only meaningful whole: its receipt pins SHA-256 hashes of
+    // GLBs the Scene document declares by byte count. Writing members straight
+    // into the output directory made a crash, a full disk or a Ctrl-C leave a
+    // directory that LOOKS like a package — and because `assertEmptySceneOutput`
+    // then refuses to overwrite it, that torn package is sticky, so the next run
+    // cannot repair it and an operator can publish it. Stage every member in a
+    // sibling directory on the same filesystem, verify the bytes landed, then move
+    // the finished package into place with one atomic rename: the output
+    // directory contains either nothing or a complete package.
+    await assertEmptySceneOutput(input.outputDir);
+    const scenePath = (0, node_path_1.join)(input.outputDir, 'scene.helix-scene.json');
+    const receiptPath = (0, node_path_1.join)(input.outputDir, 'import-receipt.json');
+    await stageSceneV2Package({
+        outputDir: input.outputDir,
+        members: [
+            ...(input.proxy ? [[colliderPath, input.proxy.bytes]] : []),
+            [detailPath, input.detail.bytes],
+            ['scene.helix-scene.json', sceneJson],
+            ['import-receipt.json', receiptJson],
+        ],
+    });
+    return {
+        scenePath,
+        receiptPath,
+        resourcePaths: input.proxy ? [detailPath, colliderPath] : [detailPath],
+        totalBytes: packageBytes,
+        scene: validation.scene,
+    };
+}
+/**
+ * Writes one complete Scene v2 package atomically: stage every member in a
+ * sibling directory on the same filesystem, verify each landed at its declared
+ * size, then promote with a single rename.
+ */
+async function stageSceneV2Package(input) {
+    const staging = (0, node_path_1.join)((0, node_path_1.dirname)(input.outputDir), `.${(0, node_path_1.basename)(input.outputDir)}.staging-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`);
+    try {
+        await (0, promises_1.mkdir)((0, node_path_1.join)(staging, 'assets'), { recursive: true });
+        await Promise.all(input.members.map(([relative, body]) => (0, promises_1.writeFile)((0, node_path_1.join)(staging, relative), body)));
+        await assertStagedPackageMembers(staging, input.members.map(([relative, body]) => [
+            relative,
+            Buffer.isBuffer(body) ? body.byteLength : Buffer.byteLength(body),
+        ]));
+        // POSIX renames a directory onto an existing EMPTY directory atomically, and
+        // `staging` is a sibling of the target so this can never cross a filesystem.
+        await (0, promises_1.rm)(input.outputDir, { recursive: true, force: true });
+        await (0, promises_1.rename)(staging, input.outputDir);
+    }
+    catch (error) {
+        await (0, promises_1.rm)(staging, { recursive: true, force: true });
+        throw error;
+    }
+}
+/**
+ * A short write is the realistic partial-failure mode and it does not throw:
+ * `writeFile` resolving says nothing about how many bytes reached the disk.
+ * Refuse to promote a staged member whose on-disk size disagrees with what the
+ * receipt and Scene document already claim about it.
+ */
+async function assertStagedPackageMembers(stagingDir, members) {
+    await Promise.all(members.map(async ([relative, expected]) => {
+        const written = (await (0, promises_1.stat)((0, node_path_1.join)(stagingDir, relative))).size;
+        if (written !== expected) {
+            throw new Error(`staged Scene package member ${relative} is ${written} bytes, expected ${expected}`);
+        }
+    }));
+}
+async function assertEmptySceneOutput(outputDir) {
+    await (0, promises_1.mkdir)(outputDir, { recursive: true });
+    const existingOutput = await (0, promises_1.readdir)(outputDir);
+    if (existingOutput.length > 0) {
+        throw new Error('Scene v2 output directory must be empty');
+    }
+}
+async function createSceneV2MultiAssetPackage(input) {
+    assertSourceReceipt(input.receipt);
+    if (!input.placements.length)
+        throw new Error('a multi-asset Scene requires at least one placement');
+    if (!input.resources.size)
+        throw new Error('a multi-asset Scene requires at least one compiled mesh');
+    // Platform caps, checked here where the offender can still be named before
+    // anything is written: HELIX_SCENE_CAPS nodes/cells/groups/resources, and the
+    // World-build endpoint's multipart file count.
+    if (input.placements.length > streamLayout_1.SCENE_V2_MAX_NODES - streamLayout_1.SCENE_V2_MAX_STREAM_GROUPS - 1) {
+        throw new Error(`${input.placements.length} placements exceed the ${streamLayout_1.SCENE_V2_MAX_NODES}-node Scene cap once collision anchors and lighting are added`);
+    }
+    // Count the files this package will ACTUALLY write, not two per mesh: a mesh
+    // with no proxy costs one GLB and two resource declarations (detail + a
+    // collider pointing back at that same detail file).
+    const meshesWithProxy = [...input.resources.values()].filter((compiled) => compiled.proxy).length;
+    // Shared textures are files and resources like any other, and a cap checked
+    // before they were counted is a cap that passes and then fails at upload.
+    const emittedFiles = input.resources.size + meshesWithProxy;
+    const emittedResources = input.resources.size * 2 + meshesWithProxy;
+    // The multipart file count is a PUBLISH-time constraint, and `loadSceneV2Package`
+    // already enforces it on the bundle list the request will actually carry. This
+    // early copy exists to name the offending pack before anything is written.
+    // Corrected 2026-09-25 (P6 W2, ADR-0004): this guard used to have a
+    // `vaultPinned` bypass, deferring it to publish for a package headed to
+    // `world scene-source vault-pin` — that command is gone (recent Worlds
+    // publish via continuum_release with zero Vault pins), so the cap is
+    // unconditional again. A world too large for it needs a different Scene
+    // architecture (composition via `mounts[]`, e.g.), not a Vault pin.
+    if (emittedFiles > exports.SCENE_V2_RESOURCE_MAX_FILES) {
+        throw new Error(`${input.resources.size} unique meshes produce ${emittedFiles} GLBs; the build endpoint accepts at most ${exports.SCENE_V2_RESOURCE_MAX_FILES} files. Compose the world from smaller mounted Scenes instead (\`world scene-source compose\`).`);
+    }
+    if (emittedResources > streamLayout_1.SCENE_V2_MAX_RESOURCES) {
+        throw new Error(`${input.resources.size} unique meshes declare ${emittedResources} resources; the Scene cap is ${streamLayout_1.SCENE_V2_MAX_RESOURCES}`);
+    }
+    for (const [key, compiled] of input.resources) {
+        assertArtifact(compiled.detail, `detail mesh ${key}`);
+        if (compiled.proxy)
+            assertArtifact(compiled.proxy, `proxy mesh ${key}`);
+        if (compiled.detail.bytes.length >= exports.SCENE_V2_RESOURCE_MAX_BYTES) {
+            throw new Error(`detail mesh ${key} exceeds the ${exports.SCENE_V2_RESOURCE_MAX_BYTES}-byte per-file cap`);
+        }
+        if (compiled.proxy && compiled.proxy.bytes.length >= exports.SCENE_V2_RESOURCE_MAX_BYTES) {
+            throw new Error(`proxy mesh ${key} exceeds the ${exports.SCENE_V2_RESOURCE_MAX_BYTES}-byte per-file cap`);
+        }
+    }
+    // Canonicalize by CONTENT hash before declaring anything: two compiler keys
+    // whose artifacts are byte-identical (the same prop exported twice, or two
+    // different meshes that simplify onto one shared proxy) must share ONE file,
+    // ONE assetId, ONE digest — the manifest validator rejects an assetId
+    // declared twice under different URIs, and honest dedup is the whole point.
+    const canonicalDetail = new Map();
+    const canonicalProxy = new Map();
+    const detailHashByKey = new Map();
+    const proxyHashByKey = new Map();
+    for (const [key, compiled] of input.resources) {
+        detailHashByKey.set(key, compiled.detail.contentSha256);
+        canonicalDetail.set(compiled.detail.contentSha256, compiled.detail);
+        if (!compiled.proxy)
+            continue;
+        proxyHashByKey.set(key, compiled.proxy.contentSha256);
+        canonicalProxy.set(compiled.proxy.contentSha256, compiled.proxy);
+    }
+    for (const placement of [...input.placements].sort((a, b) => a.name.localeCompare(b.name))) {
+        (0, types_1.assertFiniteVec3)(placement.transform.position, `placement ${placement.name} position`);
+        (0, types_1.assertFiniteVec3)(placement.transform.scale, `placement ${placement.name} scale`);
+        (0, types_1.assertFiniteVec3)(placement.worldBounds.min, `placement ${placement.name} bounds min`);
+        (0, types_1.assertFiniteVec3)(placement.worldBounds.max, `placement ${placement.name} bounds max`);
+        if (!input.resources.has(placement.detailResourceKey)) {
+            throw new Error(`placement ${placement.name} references unknown detail mesh ${placement.detailResourceKey}`);
+        }
+        if (!input.resources.has(placement.proxyResourceKey)) {
+            throw new Error(`placement ${placement.name} references unknown proxy mesh ${placement.proxyResourceKey}`);
+        }
+    }
+    const layoutPlacements = input.placements.map((placement) => ({
+        ...placement,
+        id: placementId(placement),
+    }));
+    const resourceMiB = new Map();
+    for (const key of input.resources.keys()) {
+        const compiled = input.resources.get(key);
+        const decodedBytes = (await decodedResidencyBytes(compiled.detail, `detail mesh ${key}`)) +
+            (compiled.proxy ? await decodedResidencyBytes(compiled.proxy, `proxy mesh ${key}`) : 0);
+        resourceMiB.set(key, Math.max(1 / 1024, decodedBytes / (1024 * 1024)));
+    }
+    const layout = (0, streamLayout_1.planStreamLayout)({
+        placements: layoutPlacements,
+        resourceMiB,
+        ...(input.cellSizeM !== undefined ? { cellSizeM: input.cellSizeM } : {}),
+    });
+    const stable = (0, node_crypto_1.createHash)('sha256')
+        .update(input.sourceId)
+        .update([...input.resources.keys()].sort().join('\n'))
+        .digest('hex');
+    const sceneId = `scene.import.multi.${stable.slice(0, 16)}`;
+    const rootId = `scene.root.${stable.slice(0, 12)}`;
+    const sunNodeId = `node.sun.${stable.slice(0, 12)}`;
+    const sunId = `light.sun.${stable.slice(0, 12)}`;
+    const resourceIdFor = (kind, key) => `resource.${kind}.${(0, node_crypto_1.createHash)('sha256').update(kind).update(key).digest('hex').slice(0, 12)}`;
+    const meshBaseName = (key) => `mesh-${key.slice(0, 24)}`;
+    // Detail hashes whose mesh has no proxy: their collider resource points back
+    // at the detail GLB, declared alongside it.
+    const detailBackedColliderHashes = new Set([...input.resources.values()]
+        .filter((compiled) => !compiled.proxy)
+        .map((compiled) => compiled.detail.contentSha256));
+    const detailResourceByKey = new Map();
+    const proxyResourceByKey = new Map();
+    const colliderResourceByKey = new Map();
+    const resources = [];
+    const members = [];
+    let totalResourceBytes = 0;
+    const sharedTextures = new Map();
+    for (const detailHash of [...canonicalDetail.keys()].sort()) {
+        // The FILENAME keeps the pre-lift hash (it is only a name); the declared
+        // integrity and byte count come from the artifact that actually ships.
+        const compiledDetail = await liftSharedTextures(canonicalDetail.get(detailHash), sharedTextures);
+        const detailPath = `assets/${meshBaseName(detailHash)}.detail.glb`;
+        const detailResource = resourceIdFor('detail', detailHash);
+        resources.push(resource(detailResource, detailPath, compiledDetail));
+        if (detailBackedColliderHashes.has(detailHash)) {
+            resources.push(resource(resourceIdFor('collider', detailHash), detailPath, compiledDetail, 'collider'));
+        }
+        members.push([detailPath, compiledDetail.bytes]);
+        totalResourceBytes += compiledDetail.bytes.length;
+    }
+    for (const proxyHash of [...canonicalProxy.keys()].sort()) {
+        const compiledProxy = await liftSharedTextures(canonicalProxy.get(proxyHash), sharedTextures);
+        const proxyPath = `assets/${meshBaseName(proxyHash)}.proxy.glb`;
+        const proxyResource = resourceIdFor('proxy', proxyHash);
+        const colliderResource = resourceIdFor('collider', proxyHash);
+        resources.push(resource(proxyResource, proxyPath, compiledProxy), resource(colliderResource, proxyPath, compiledProxy, 'collider'));
+        members.push([proxyPath, compiledProxy.bytes]);
+        totalResourceBytes += compiledProxy.bytes.length;
+    }
+    // Shared textures. Declared `required: false` because a mesh renders (untextured)
+    // without them, so a single failed texture must not fail the whole Scene.
+    for (const sha of [...sharedTextures.keys()].sort()) {
+        const texture = sharedTextures.get(sha);
+        const texturePath = `assets/${texture.filename}`;
+        resources.push({
+            id: `resource.texture.${sha.slice(0, 12)}`,
+            kind: 'texture',
+            source: { kind: 'bundle', assetId: `asset.${sha.slice(0, 24)}`, uri: texturePath },
+            integrity: { sha256: sha },
+            bytes: texture.bytes.length,
+            mimeType: 'image/ktx2',
+            required: false,
+        });
+        members.push([texturePath, texture.bytes]);
+        totalResourceBytes += texture.bytes.length;
+    }
+    for (const key of input.resources.keys()) {
+        const detailHash = detailHashByKey.get(key);
+        detailResourceByKey.set(key, resourceIdFor('detail', detailHash));
+        const proxyHash = proxyHashByKey.get(key);
+        if (proxyHash === undefined) {
+            // No proxy: the collider stands on this mesh's own detail GLB. A collider
+            // resource id derived from a proxy that was never written would dangle.
+            colliderResourceByKey.set(key, resourceIdFor('collider', detailHash));
+            continue;
+        }
+        proxyResourceByKey.set(key, resourceIdFor('proxy', proxyHash));
+        colliderResourceByKey.set(key, resourceIdFor('collider', proxyHash));
+    }
+    const nodes = [];
+    const collisionSets = [];
+    const rootNodeIds = [];
+    let colliderIndex = 0;
+    // Instance node ids grouped by cell id, so each group's collision anchor and
+    // the sun join their neighbourhood deterministically.
+    const cellNodeIds = new Map();
+    for (const placement of layout.placements) {
+        const nodeId = `node.asset.${placement.id}`;
+        const members = cellNodeIds.get(placement.cellId);
+        if (members)
+            members.push(nodeId);
+        else
+            cellNodeIds.set(placement.cellId, [nodeId]);
+    }
+    layout.groups.forEach((group, groupIndex) => {
+        const anchorNodeId = `node.collision.${stable.slice(0, 8)}.${groupIndex}`;
+        const setId = `collision.group.${stable.slice(0, 8)}.${groupIndex}`;
+        const firstCell = group.cells[0];
+        if (!firstCell)
+            throw new Error('stream layout produced a group without cells');
+        const firstCellNodes = cellNodeIds.get(firstCell.id) ?? [];
+        cellNodeIds.set(firstCell.id, firstCellNodes);
+        // The group's collision anchor holds every proxy collider for this group's
+        // instances at identity, so collider transforms ARE the placement transforms
+        // and streamed content always arrives with the geometry it stands on.
+        const colliders = layout.placements
+            .filter((placement) => placement.groupId === group.id)
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((placement) => ({
+            id: `collider.${stable.slice(0, 8)}.${colliderIndex++}`,
+            shape: 'triangle-mesh',
+            resource: colliderResourceByKey.get(placement.proxyResourceKey),
+            transform: placement.transform,
+        }));
+        collisionSets.push({ id: setId, node: anchorNodeId, static: colliders });
+        nodes.push({
+            id: anchorNodeId,
+            transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+            streamGroup: group.id,
+            components: [{ type: 'collision.proxy-set', set: setId }],
+        });
+        rootNodeIds.push(anchorNodeId);
+        firstCellNodes.push(anchorNodeId);
+        if (groupIndex === 0) {
+            nodes.push({
+                id: sunNodeId,
+                transform: {
+                    position: [0, 0, 0],
+                    rotation: [-0.4030582, 0.272532008, 0.127083762, 0.864361099],
+                    scale: [1, 1, 1],
+                },
+                streamGroup: group.id,
+                components: [{ type: 'light.attachments', lights: [sunId] }],
+            });
+            rootNodeIds.push(sunNodeId);
+            firstCellNodes.push(sunNodeId);
+        }
+        for (const placement of layout.placements.filter((candidate) => candidate.groupId === group.id)) {
+            const nodeId = `node.asset.${placement.id}`;
+            const detailResource = detailResourceByKey.get(placement.detailResourceKey);
+            const proxyResource = proxyResourceByKey.get(placement.proxyResourceKey);
+            // LOD distance is measured from the NODE ORIGIN — this instance's own
+            // transform.position — out to the furthest corner of its own extent, so
+            // the range sizes to THAT asset and nothing else. Measuring |worldBounds|
+            // instead measures from the WORLD origin, which makes the range grow with
+            // how far the pack was authored from (0,0,0): a 2 m prop at (500,0,500)
+            // gets a 741 m detail range and its proxy never streams in.
+            const cornerDistanceM = Math.hypot(...[0, 1, 2].map((axis) => Math.max(Math.abs(placement.worldBounds.min[axis] - placement.transform.position[axis]), Math.abs(placement.worldBounds.max[axis] - placement.transform.position[axis]))));
+            const detailMaxDistanceM = Math.ceil(cornerDistanceM) + 32;
+            nodes.push({
+                id: nodeId,
+                resource: detailResource,
+                transform: placement.transform,
+                streamGroup: group.id,
+                // A mesh whose proxy did not measurably beat its detail declares ONE
+                // level: `only-available`. Two identical levels bought nothing but a
+                // second file and a flat-grey pop past the detail range.
+                lod: proxyResource
+                    ? {
+                        selection: 'distance',
+                        levels: [
+                            { level: 0, resource: detailResource, maxDistanceM: detailMaxDistanceM },
+                            { level: 1, resource: proxyResource },
+                        ],
+                    }
+                    : { selection: 'only-available', levels: [{ level: 0, resource: detailResource }] },
+                components: [
+                    { type: 'render.mesh', castShadow: true, receiveShadow: true },
+                ],
+            });
+            rootNodeIds.push(nodeId);
+        }
+    });
+    const streamGroups = layout.groups.map((group) => ({
+        id: group.id,
+        mode: 'distance',
+        priority: group.priority,
+        dependencies: [],
+        estimatedMemoryMiB: group.estimatedMemoryMiB,
+        cells: group.cells.map((cell) => ({
+            id: cell.id,
+            bounds: cell.bounds,
+            nodes: cellNodeIds.get(cell.id) ?? [],
+        })),
+    }));
+    const boundsUnion = layout.placements.reduce((union, placement) => ({
+        min: union.min.map((value, axis) => Math.min(value, placement.worldBounds.min[axis])),
+        max: union.max.map((value, axis) => Math.max(value, placement.worldBounds.max[axis])),
+    }), {
+        min: [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY],
+        max: [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY],
+    });
+    // Residency honesty: no eager group means the union is just the largest
+    // single activation; give the runtime headroom above exactly that number
+    // rather than pretending the estimate IS the budget.
+    const residencyCommitmentMiB = Math.max(...layout.groups.map((group) => group.estimatedMemoryMiB), 1);
+    const memoryBudgetMiB = Math.max(64, Math.ceil(residencyCommitmentMiB * 1.5));
+    const spawnPosition = input.spawn?.position ?? [
+        (boundsUnion.min[0] + boundsUnion.max[0]) / 2,
+        boundsUnion.max[1] + 1.9,
+        (boundsUnion.min[2] + boundsUnion.max[2]) / 2,
+    ];
+    const scene = {
+        format: 'helix.scene',
+        version: 2,
+        id: sceneId,
+        revision: '0'.repeat(16),
+        integrity: { sha256: '0'.repeat(64) },
+        title: input.title,
+        units: 'meters',
+        coordinateSystem: { handedness: 'right', up: '+Y', forward: '-Z' },
+        profiles: {
+            world: {
+                scene: rootId,
+                kind: 'world',
+                persistence: 'session',
+                maxPlayers: 1,
+                overrideAuthority: 'none',
+                runtimePolicy: {
+                    memoryBudgetMiB,
+                    streamRadiusM: layout.streamRadiusM,
+                    allowSurfaceOverrides: false,
+                    allowItemPlacement: false,
+                },
+            },
+        },
+        scenes: [{ id: rootId, nodes: rootNodeIds, streamGroups: layout.groups.map((group) => group.id) }],
+        resources,
+        nodes,
+        itemDefinitions: [],
+        itemInstances: [],
+        terrain: { kind: 'none' },
+        environment: {
+            background: true,
+            intensityScale: 1,
+            rotationYDeg: 0,
+            exposureEV100: 0,
+            fallbackColor: '#8aa4b8',
+            required: false,
+        },
+        lights: [
+            {
+                id: sunId,
+                node: sunNodeId,
+                type: 'directional',
+                color: '#fff4e0',
+                illuminanceLux: 2.4,
+                shadow: { enabled: false, mapSize: 1024 },
+                required: false,
+                fallback: { unsupported: 'unshadowed' },
+            },
+        ],
+        spawns: [
+            {
+                id: 'spawn.main',
+                position: spawnPosition,
+                rotation: [0, 0, 0, 1],
+                profileAccess: ['world'],
+                clearanceRadiusM: 0.45,
+                clearanceHeightM: 1.9,
+            },
+        ],
+        collision: { sets: collisionSets },
+        navigation: {
+            walkableSurfaces: [],
+            agent: { radiusM: 0.35, heightM: 1.8, stepHeightM: 0.32, maxSlopeDeg: 48 },
+            navmesh: null,
+            fallback: 'physics-walkability',
+        },
+        placement: {
+            bounds: boundsUnion,
+            maxItemInstances: 0,
+            snapGridM: 0.05,
+            allowedProfiles: [],
+        },
+        surfaces: [],
+        materials: [],
+        behaviors: [],
+        streamGroups,
+        capabilities: { required: ['render.mesh/1'], optional: [] },
+        runtimeExtensions: [
+            {
+                id: 'ext.web.three-renderer',
+                extension: 'web.three-renderer/1',
+                runtime: 'web',
+                targetNodes: [sunNodeId],
+                required: false,
+                fallback: 'portable',
+                parameters: {
+                    ambientColor: '#ccd9e8',
+                    ambientIntensity: 2.0,
+                    hemisphereSkyColor: '#bcd8f5',
+                    hemisphereGroundColor: '#7d766a',
+                    hemisphereIntensity: 1.6,
+                    pointDecay: 2,
+                    directionalShadowExtent: 60,
+                    directionalShadowNear: 0.5,
+                    directionalShadowFar: 400,
+                },
+            },
+        ],
+        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(`generated multi-asset Scene v2 is invalid: ${validation.errors.join('; ')}`);
+    }
+    const sceneJson = (0, types_1.serializeSceneDocument)(validation.scene);
+    const packageBytes = totalResourceBytes + Buffer.byteLength(sceneJson);
+    if (packageBytes > exports.SCENE_V2_PACKAGE_MAX_BYTES) {
+        throw new Error(`generated Scene package exceeds the ${exports.SCENE_V2_PACKAGE_MAX_BYTES}-byte build cap`);
+    }
+    const receiptJson = `${JSON.stringify({
+        schemaVersion: input.receipt.schemaVersion,
+        kind: 'multi-asset-scene-import/1',
+        sourceId: input.receipt.sourceId,
+        originalSha256: input.receipt.originalSha256,
+        attribution: input.receipt.attribution,
+        rights: { ...input.receipt.rights },
+        conversion: input.receipt.conversion,
+        unsupported: input.receipt.unsupported,
+        assets: {
+            placements: input.placements.length,
+            uniqueMeshes: input.resources.size,
+            cells: layout.groups.reduce((sum, group) => sum + group.cells.length, 0),
+            streamGroups: layout.groups.length,
+            cellSizeM: layout.cellSizeM,
+            streamRadiusM: layout.streamRadiusM,
+            memoryBudgetMiB,
+            residencyCommitmentMiB,
+            proxiesKept: meshesWithProxy,
+            proxiesDropped: input.resources.size - meshesWithProxy,
+            resourceFiles: emittedFiles,
+        },
+        ...(input.proxyReductions
+            ? {
+                proxyReduction: {
+                    summary: (0, proxy_1.summarizeProxyReductions)(input.proxyReductions),
+                    meshes: [...input.proxyReductions].sort((a, b) => a.name.localeCompare(b.name)),
+                },
+            }
+            : {}),
+        rights_status_note: 'rights block is declared explicitly by the import profile; licenseClass identifies the license family actually granted by the source',
+        outputs: {
+            resources: [
+                ...[...canonicalDetail.entries()].map(([hash, compiled]) => artifactReceipt(compiled, `assets/${meshBaseName(hash)}.detail.glb`)),
+                ...[...canonicalProxy.entries()].map(([hash, compiled]) => artifactReceipt(compiled, `assets/${meshBaseName(hash)}.proxy.glb`)),
+            ],
+            scene: {
+                id: scene.id,
+                revision: scene.revision,
+                integritySha256: scene.integrity.sha256,
+            },
+        },
+        spawn: {
+            position: spawnPosition,
+            groundProbe: input.spawn
+                ? {
+                    source: 'placed-proxy-geometry',
+                    groundY: input.spawn.groundY,
+                    rejectedCandidates: input.spawn.rejectedCandidates,
+                }
+                : {
+                    source: 'bounds-fallback',
+                    groundY: boundsUnion.max[1],
+                    rejectedCandidates: 0,
+                },
+        },
+        unsupportedCapabilities: ['nested-scenes', 'scene-shards'],
+    }, null, 2)}\n`;
+    await assertEmptySceneOutput(input.outputDir);
+    const scenePath = (0, node_path_1.join)(input.outputDir, 'scene.helix-scene.json');
+    const receiptPath = (0, node_path_1.join)(input.outputDir, 'import-receipt.json');
+    await stageSceneV2Package({
+        outputDir: input.outputDir,
+        members: [...members, ['scene.helix-scene.json', sceneJson], ['import-receipt.json', receiptJson]],
+    });
+    return {
+        scenePath,
+        receiptPath,
+        resourcePaths: members.map(([relative]) => relative),
+        totalBytes: packageBytes,
+        scene: validation.scene,
+    };
+}
+function placementId(placement) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(placement.name)
+        .update(JSON.stringify(placement.transform.position))
+        .update(JSON.stringify(placement.transform.rotation))
+        .update(JSON.stringify(placement.transform.scale))
+        .digest('hex')
+        .slice(0, 12);
+}
+function assertSourceReceipt(receipt) {
+    if (!/^[a-f0-9]{64}$/.test(receipt.originalSha256)) {
+        throw new Error('source receipt original SHA-256 is invalid');
+    }
+    (0, types_1.assertFiniteVec3)(receipt.sourceOrigin, 'source receipt origin');
+    if (receipt.sourceCrs !== null && !/^EPSG:\d+(?:\+\d+)?$/.test(receipt.sourceCrs)) {
+        throw new Error('source receipt CRS must be null or a finite EPSG identifier');
+    }
+    // License-agnostic: Helsinki's CC BY 4.0 is one valid value, not the only
+    // one. What is NOT negotiable is that the attribution is complete and the
+    // recipient-rights statement is explicit.
+    if (!receipt.attribution.license.trim() ||
+        !/^https:\/\/\S+$/.test(receipt.attribution.licenseUrl) ||
+        !receipt.attribution.creator.trim() ||
+        !receipt.attribution.title.trim() ||
+        !receipt.attribution.url.trim() ||
+        !receipt.attribution.changes.trim()) {
+        throw new Error('source receipt must preserve complete license attribution and changes');
+    }
+    (0, types_1.assertSourceRights)(receipt.rights);
+}
+/**
+ * Moves a mesh's embedded KTX2 payloads into `shared`, leaving the mesh
+ * referencing them by filename, and returns the rewritten artifact.
+ *
+ * This is the LAST thing done to a mesh's bytes, and it has to be. gltf-transform
+ * cannot read a GLB whose images carry a uri instead of a bufferView -- not to
+ * simplify it, not to measure it, not at all ("Missing resource URI or buffer
+ * view", verified both with the uri present and with it stripped). So every
+ * pass that inspects geometry runs first, on the embedded bytes, and this runs
+ * at emit time on the way to disk. Anything added later that re-reads an
+ * artifact must run BEFORE this, or it will fail on textured meshes only.
+ *
+ * Keyed by payload sha256, so a texture on forty meshes becomes one file, one
+ * download and one GPU image. The filename IS the content hash, which is what
+ * lets separately-published groups resolve to bytes an earlier group fetched.
+ */
+async function liftSharedTextures(artifact, shared) {
+    if (!artifact.bytes.includes('image/ktx2'))
+        return artifact;
+    const document = await (0, gltfIo_1.sceneGltfIo)().readBinary(new Uint8Array(artifact.bytes));
+    const uriByImageName = new Map();
+    for (const texture of document.getRoot().listTextures()) {
+        if (texture.getMimeType() !== 'image/ktx2')
+            continue;
+        const image = texture.getImage();
+        if (!image)
+            continue;
+        const payload = Buffer.from(image);
+        const sha = (0, node_crypto_1.createHash)('sha256').update(payload).digest('hex');
+        const filename = `tex-${sha.slice(0, 24)}.ktx2`;
+        if (!shared.has(sha))
+            shared.set(sha, { filename, bytes: payload });
+        texture.setName(filename);
+        texture.setImage(null);
+        texture.setURI(filename);
+        uriByImageName.set(filename, filename);
+    }
+    if (uriByImageName.size === 0)
+        return artifact;
+    const written = Buffer.from(await (0, gltfIo_1.sceneGltfIo)().writeBinary(document));
+    const bytes = Buffer.from((0, externalTextures_1.externalizeGlbTextureUris)(written, uriByImageName));
+    return { ...artifact, bytes, contentSha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex') };
+}
+function resource(id, uri, artifact, 
+// 'texture' is in the union so shared textures, which are built inline rather
+// than through this helper, still widen the declared resource type.
+kind = 'model') {
+    return {
+        id,
+        kind,
+        source: { kind: 'bundle', assetId: `asset.${artifact.contentSha256.slice(0, 24)}`, uri },
+        integrity: { sha256: artifact.contentSha256 },
+        bytes: artifact.bytes.length,
+        mimeType: 'model/gltf-binary',
+        required: true,
+    };
+}
+/**
+ * What the runtime HOLDS for one compiled GLB, which is not what it downloads.
+ * File size is the compressed transfer cost: geometry may be quantized and
+ * every texture travels as PNG/JPEG, while residency is decoded attribute and
+ * index buffers plus RGBA texture levels. Billing a memory budget at file size
+ * therefore understates the exact number the budget exists to protect, and the
+ * validator's residency check passes on figures that are simply not true.
+ *
+ * Shared accessors are counted once; textures are counted as RGBA8 plus the
+ * third the mip chain adds. The file's own byte count is a floor, never the
+ * answer.
+ */
+async function decodedResidencyBytes(artifact, label) {
+    let document;
+    try {
+        document = await (0, gltfIo_1.sceneGltfIo)().readBinary(new Uint8Array(artifact.bytes));
+    }
+    catch (error) {
+        throw new Error(`${label} is not a readable GLB: ${error.message}`);
+    }
+    let bytes = 0;
+    const counted = new Set();
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives()) {
+            for (const accessor of [...primitive.listAttributes(), primitive.getIndices()]) {
+                if (!accessor || counted.has(accessor))
+                    continue;
+                counted.add(accessor);
+                bytes += accessor.getArray()?.byteLength ?? 0;
+            }
+        }
+    }
+    for (const texture of document.getRoot().listTextures()) {
+        const size = texture.getSize();
+        if (!size)
+            continue;
+        bytes += Math.ceil(size[0] * size[1] * 4 * (4 / 3));
+    }
+    return Math.max(bytes, artifact.bytes.length);
+}
+function assertArtifact(artifact, label) {
+    if (!artifact.bytes.length)
+        throw new Error(`${label} GLB is empty`);
+    if (!/^[a-f0-9]{64}$/.test(artifact.contentSha256))
+        throw new Error(`${label} content hash is invalid`);
+    const actual = (0, node_crypto_1.createHash)('sha256').update(artifact.bytes).digest('hex');
+    if (actual !== artifact.contentSha256)
+        throw new Error(`${label} content hash does not match its bytes`);
+}
+function artifactReceipt(artifact, path) {
+    return {
+        path,
+        stableId: `asset.${artifact.contentSha256.slice(0, 24)}`,
+        contentSha256: artifact.contentSha256,
+        bytes: artifact.bytes.length,
+        bounds: artifact.bounds,
+        counts: artifact.summary,
+    };
+}
+//# sourceMappingURL=package.js.map