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

package/dist/sceneImport/composeMounts.js

@@ -0,0 +1,687 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChildScene = resolveChildScene;
+exports.sceneFootprint = sceneFootprint;
+exports.transformBounds = transformBounds;
+exports.composeMountedScene = composeMountedScene;
+exports.composeMountsPackage = composeMountsPackage;
+exports.readComposePlan = readComposePlan;
+// Compose a parent Scene v2 document that MOUNTS already-published child Scenes.
+//
+// `compile-pack` turns meshes into one flat document, and a flat document is
+// capped at 1 MiB / 4,096 nodes / 2,048 resources. A world larger than that cap
+// is authored as a tree: each part is published on its own, and a parent pins
+// them by content hash in `mounts[]` and places them with `scene.mount` node
+// components. Nothing here uploads geometry — the parent is the pins alone.
+//
+// The whole point of doing this in the CLI rather than by hand is that the
+// backend's `resolveMount` runs the SAME checks at publish and answers 422.
+// Discovering a mirrored budget is one MiB out after a multi-minute upload is
+// the expensive way to learn it, so every check the server makes is made here
+// first, against the child's REAL published bytes, before anything is written.
+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");
+/** Capability a document must require before it may declare `mounts`. */
+const MOUNT_CAPABILITY = 'helix.scene-mount/1';
+const SCENE_DOCUMENT_FILENAME = 'scene.helix-scene.json';
+const IMPORT_RECEIPT_FILENAME = 'import-receipt.json';
+/** `$defs/id`: lower-case dot/dash/underscore segments, nothing else. */
+const SCENE_ID_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const REVISION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * `MAX_RESIDENT_MOUNTS` in the helixgame.com Scene v2 streamer: how many child
+ * Scenes one streamer instance keeps live. Mirrored here because the format's
+ * own cap is 64 and the difference between the two is a world with holes in it.
+ */
+const MAX_RESIDENT_MOUNTS = 8;
+const defaultFetch = async (url) => {
+    const response = await fetch(url, { redirect: 'follow' });
+    const bytes = Buffer.from(await response.arrayBuffer());
+    return { ok: response.ok, status: response.status, bytes };
+};
+function fail(message) {
+    throw new Error(message);
+}
+/**
+ * Read one child's bytes and answer every question the backend's `resolveMount`
+ * will ask, before a single byte of the parent is written.
+ *
+ * The child is addressed by its own document digest, which is also its storage
+ * address, so a fetched document that hashes to something else is not a stale
+ * mirror to tolerate — it is a different document, and the pin would be a lie.
+ */
+async function resolveChildScene(entry, options) {
+    const sources = [entry.entryUrl, entry.receipt, entry.document].filter((value) => value !== undefined);
+    if (sources.length !== 1) {
+        fail(`mount "${entry.id}": name exactly one of entryUrl, receipt or document`);
+    }
+    let origin;
+    let bytes;
+    let published;
+    if (entry.receipt !== undefined) {
+        const receiptPath = (0, node_path_1.resolve)(entry.receipt);
+        let parsed;
+        try {
+            parsed = JSON.parse(await (0, promises_1.readFile)(receiptPath, 'utf8'));
+        }
+        catch (err) {
+            fail(`mount "${entry.id}": ${receiptPath} is not readable JSON (${String(err)})`);
+        }
+        const entryUrl = parsed?.receipt?.scene
+            ?.entryUrl;
+        if (typeof entryUrl !== 'string' || !entryUrl) {
+            fail(`mount "${entry.id}": ${receiptPath} has no receipt.scene.entryUrl — is it a scene-source publish receipt?`);
+        }
+        origin = entryUrl;
+        ({ bytes, published } = await readOverNetwork(entry.id, entryUrl, options.fetchImpl));
+    }
+    else if (entry.entryUrl !== undefined) {
+        origin = entry.entryUrl;
+        ({ bytes, published } = await readOverNetwork(entry.id, entry.entryUrl, options.fetchImpl));
+    }
+    else {
+        origin = (0, node_path_1.resolve)(entry.document);
+        bytes = await (0, promises_1.readFile)(origin);
+        published = false;
+    }
+    const digest = (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+    const text = bytes.toString('utf8');
+    // parseSceneDocument also enforces the 1 MiB document cap, so a child that a
+    // runtime could never load is refused here rather than at the parent's first
+    // mount activation.
+    const parsedScene = (0, helix_manifest_1.parseSceneDocument)(text);
+    if (!parsedScene.valid) {
+        if (!text.trimStart().startsWith('{')) {
+            fail(`mount "${entry.id}": ${origin} is not a Scene document (${bytes.length} bytes, sha256 ${digest})`);
+        }
+        fail(`mount "${entry.id}": ${origin} is not a valid Scene document: ${parsedScene.errors.join('; ')}`);
+    }
+    const scene = parsedScene.scene;
+    // The child's `integrity` field is self-referential, so it proves nothing on
+    // its own; recompute it from the content the same way the loader does.
+    if (!(0, helix_manifest_1.verifySceneDocumentIntegrity)(scene)) {
+        fail(`mount "${entry.id}": ${origin} fails its own integrity check — the document has been altered`);
+    }
+    const sha256 = scene.integrity.sha256;
+    // A published child lives at `scene-v2/<its own digest>/`. If the URL segment
+    // and the document disagree, the CDN is serving something else at that path
+    // and the pin derived from the URL would resolve to the wrong Scene.
+    const urlHash = /\/scene-v2\/([0-9a-f]{64})\//.exec(origin)?.[1];
+    if (urlHash && urlHash !== sha256) {
+        fail(`mount "${entry.id}": ${origin} is addressed as ${urlHash} but the document's digest is ${sha256}`);
+    }
+    const profileId = entry.profile ?? options.defaultProfile;
+    const profile = scene.profiles[profileId];
+    if (!profile) {
+        fail(`mount "${entry.id}": child ${scene.id}@${scene.revision} declares no profile "${profileId}" (has: ${Object.keys(scene.profiles).join(', ') || 'none'})`);
+    }
+    if (profile.kind !== 'world') {
+        fail(`mount "${entry.id}": child profile "${profileId}" is kind "${profile.kind}"; a mounted Scene must be a world`);
+    }
+    // The web runtime has no component host, and native publication refuses any
+    // document carrying behaviors at all. Name the CHILD here rather than letting
+    // the parent's publish fail with the parent's id in the message.
+    if (scene.behaviors.length) {
+        fail(`mount "${entry.id}": child ${scene.id}@${scene.revision} declares ${scene.behaviors.length} behavior(s); a mounted Scene cannot carry behaviors`);
+    }
+    // Runtime extensions are NOT the same case as behaviors, and treating them as
+    // one makes every CLI-imported Scene unmountable: `compile-pack` emits
+    // `web.three-renderer/1` on every Scene it produces. Those are declarative
+    // renderer hints with `required: false, fallback: 'portable'`; a mounted
+    // child's are ignored, because the parent owns the renderer. What cannot be
+    // honoured is a child that DEMANDS one — the same rule the web plan builder
+    // and the backend's resolveMount both apply.
+    for (const extension of scene.runtimeExtensions) {
+        const canFallback = extension.fallback === 'portable' || extension.fallback === 'omit';
+        if (extension.required || !canFallback) {
+            fail(`mount "${entry.id}": child ${scene.id}@${scene.revision} requires runtime extension ${extension.extension}, which a mount cannot grant — the parent owns the renderer`);
+        }
+    }
+    const depth = scene.mountDepth ?? 0;
+    if (depth >= helix_manifest_1.HELIX_SCENE_CAPS.mountDepth) {
+        fail(`mount "${entry.id}": child ${scene.id}@${scene.revision} is already ${depth} levels deep; mounting it would exceed the depth-${helix_manifest_1.HELIX_SCENE_CAPS.mountDepth} cap`);
+    }
+    return {
+        entry,
+        origin,
+        published,
+        scene,
+        sha256,
+        profileId,
+        budgetMiB: profile.runtimePolicy.memoryBudgetMiB,
+        depth,
+        childBounds: sceneFootprint(scene, profileId),
+    };
+}
+async function readOverNetwork(mountId, url, fetchImpl) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        fail(`mount "${mountId}": ${url} is not a URL`);
+    }
+    if (parsedUrl.protocol !== 'https:' && parsedUrl.protocol !== 'http:') {
+        fail(`mount "${mountId}": ${url} must be an http(s) URL`);
+    }
+    const response = await (fetchImpl ?? defaultFetch)(url);
+    if (!response.ok) {
+        fail(`mount "${mountId}": ${url} answered HTTP ${response.status} — a mount may only pin a Scene that is published on this lane`);
+    }
+    return { bytes: response.bytes, published: true };
+}
+/**
+ * A child's footprint, taken from the activation volumes it already authored.
+ *
+ * Stream-cell bounds are the child compiler's own measurement of where its
+ * geometry is; node transforms are pivots and would under-report a mesh that
+ * extends away from its origin. Cells outside the mounted profile's root are
+ * not loaded, so they are not part of the footprint either.
+ */
+function sceneFootprint(scene, profileId) {
+    const profile = scene.profiles[profileId];
+    const root = profile ? scene.scenes.find((entry) => entry.id === profile.scene) : undefined;
+    const groupIds = new Set(root?.streamGroups ?? scene.streamGroups.map((group) => group.id));
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let seen = false;
+    for (const group of scene.streamGroups) {
+        if (!groupIds.has(group.id))
+            continue;
+        for (const cell of group.cells) {
+            seen = true;
+            for (let axis = 0; axis < 3; axis += 1) {
+                min[axis] = Math.min(min[axis], cell.bounds.min[axis]);
+                max[axis] = Math.max(max[axis], cell.bounds.max[axis]);
+            }
+        }
+    }
+    if (!seen)
+        fail(`Scene ${scene.id}@${scene.revision} declares no stream cells to measure`);
+    return { min, max };
+}
+/** Rotate/scale/translate an AABB's eight corners and re-fit an AABB to them. */
+function transformBounds(bounds, position, rotation, scale) {
+    const [qx, qy, qz, qw] = rotation;
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (let corner = 0; corner < 8; corner += 1) {
+        const point = [
+            (corner & 1 ? bounds.max : bounds.min)[0] * scale,
+            (corner & 2 ? bounds.max : bounds.min)[1] * scale,
+            (corner & 4 ? bounds.max : bounds.min)[2] * scale,
+        ];
+        // q * v * q^-1, expanded.
+        const ix = qw * point[0] + qy * point[2] - qz * point[1];
+        const iy = qw * point[1] + qz * point[0] - qx * point[2];
+        const iz = qw * point[2] + qx * point[1] - qy * point[0];
+        const iw = -qx * point[0] - qy * point[1] - qz * point[2];
+        const rotated = [
+            ix * qw + iw * -qx + iy * -qz - iz * -qy + position[0],
+            iy * qw + iw * -qy + iz * -qx - ix * -qz + position[1],
+            iz * qw + iw * -qz + ix * -qy - iy * -qx + position[2],
+        ];
+        for (let axis = 0; axis < 3; axis += 1) {
+            min[axis] = Math.min(min[axis], rotated[axis]);
+            max[axis] = Math.max(max[axis], rotated[axis]);
+        }
+    }
+    return { min, max };
+}
+/**
+ * Build the parent document.
+ *
+ * One mount = one node = one stream group = one cell. A mount node's TRANSFORM
+ * places the child's geometry; the CELL's bounds decide when it activates, and
+ * the two are independent on purpose: children cut out of one shared coordinate
+ * space are mounted at identity and would otherwise all sit in one cell at the
+ * origin and stream as a single unit.
+ */
+function composeMountedScene(plan, children) {
+    const warnings = [];
+    const profileId = plan.profile ?? 'world';
+    if (!SCENE_ID_PATTERN.test(plan.sceneId))
+        fail(`sceneId "${plan.sceneId}" is not a valid Scene id`);
+    if (!REVISION_PATTERN.test(plan.revision))
+        fail(`revision "${plan.revision}" is not a valid revision`);
+    if (!SCENE_ID_PATTERN.test(profileId))
+        fail(`profile "${profileId}" is not a valid id`);
+    if (!children.length)
+        fail('a composed Scene needs at least one mount');
+    if (children.length > helix_manifest_1.HELIX_SCENE_CAPS.mounts) {
+        fail(`${children.length} mounts exceed the cap of ${helix_manifest_1.HELIX_SCENE_CAPS.mounts}`);
+    }
+    const rootId = 'scene.root';
+    const mounts = [];
+    const nodes = [];
+    const streamGroups = [];
+    const summary = [];
+    const worldMin = [Infinity, Infinity, Infinity];
+    const worldMax = [-Infinity, -Infinity, -Infinity];
+    const seenIds = new Set();
+    for (const child of children) {
+        const entry = child.entry;
+        if (!SCENE_ID_PATTERN.test(entry.id))
+            fail(`mount id "${entry.id}" is not a valid id`);
+        if (seenIds.has(entry.id))
+            fail(`mount id "${entry.id}" is declared twice`);
+        seenIds.add(entry.id);
+        const position = entry.position ?? [0, 0, 0];
+        const rotation = entry.rotation ?? [0, 0, 0, 1];
+        const scale = entry.scale ?? 1;
+        if (!(scale > 0))
+            fail(`mount "${entry.id}": scale must be positive (a mount cannot be mirrored)`);
+        const bounds = padBounds(entry.bounds ?? transformBounds(child.childBounds, position, rotation, scale), entry.padM ?? 2);
+        for (let axis = 0; axis < 3; axis += 1) {
+            worldMin[axis] = Math.min(worldMin[axis], bounds.min[axis]);
+            worldMax[axis] = Math.max(worldMax[axis], bounds.max[axis]);
+        }
+        const suffix = entry.id.replace(/^mount[._-]/, '');
+        const nodeId = `node.${suffix}`;
+        const groupId = `group.${suffix}`;
+        const cellId = `cell.${suffix}`;
+        if (!SCENE_ID_PATTERN.test(nodeId))
+            fail(`mount "${entry.id}" produces an invalid node id "${nodeId}"`);
+        mounts.push({
+            id: entry.id,
+            scene: { id: child.scene.id, revision: child.scene.revision },
+            integrity: { sha256: child.sha256 },
+            profile: child.profileId,
+            budgetMiB: child.budgetMiB,
+            depth: child.depth,
+        });
+        nodes.push({
+            id: nodeId,
+            transform: { position, rotation, scale: [scale, scale, scale] },
+            streamGroup: groupId,
+            components: [{ type: 'scene.mount', mount: entry.id }],
+        });
+        streamGroups.push({
+            id: groupId,
+            mode: entry.mode ?? 'distance',
+            priority: entry.priority ?? 500,
+            dependencies: [],
+            // The group must commit at least what its mounted Scene commits, or
+            // publication refuses it. Mirroring exactly keeps the parent's own
+            // max-over-activations commitment honest.
+            estimatedMemoryMiB: child.budgetMiB,
+            cells: [{ id: cellId, bounds, nodes: [nodeId] }],
+        });
+        summary.push({
+            id: entry.id,
+            scene: child.scene.id,
+            revision: child.scene.revision,
+            sha256: child.sha256,
+            budgetMiB: child.budgetMiB,
+            depth: child.depth,
+            published: child.published,
+            bounds,
+            mode: entry.mode ?? 'distance',
+        });
+        if (!child.published) {
+            warnings.push(`mount "${entry.id}" was resolved from a local file, so nothing proves ${child.scene.id}@${child.scene.revision} is published on this lane; publication will 422 if it is not`);
+        }
+    }
+    const authoredLights = [];
+    const lightNodes = [];
+    for (const entry of plan.lights ?? []) {
+        if (!SCENE_ID_PATTERN.test(entry.id))
+            fail(`light id "${entry.id}" is not a valid id`);
+        if (seenIds.has(entry.id))
+            fail(`light id "${entry.id}" collides with another authored id`);
+        seenIds.add(entry.id);
+        const nodeId = `node.${entry.id}`;
+        lightNodes.push({
+            id: nodeId,
+            transform: {
+                position: entry.position ?? [0, 0, 0],
+                rotation: entry.rotation ?? [0, 0, 0, 1],
+                scale: [1, 1, 1],
+            },
+            streamGroup: 'group.lighting',
+            components: [{ type: 'light.attachments', lights: [entry.id] }],
+        });
+        const common = {
+            id: entry.id,
+            node: nodeId,
+            color: entry.color,
+            shadow: entry.shadow ?? { enabled: false, mapSize: 512 },
+            required: entry.required ?? false,
+            fallback: { unsupported: 'unshadowed' },
+        };
+        authoredLights.push(entry.type === 'directional'
+            ? { ...common, type: 'directional', illuminanceLux: entry.illuminanceLux }
+            : entry.type === 'point'
+                ? {
+                    ...common,
+                    type: 'point',
+                    luminousIntensityCandela: entry.luminousIntensityCandela,
+                    rangeM: entry.rangeM,
+                }
+                : {
+                    ...common,
+                    type: 'spot',
+                    luminousIntensityCandela: entry.luminousIntensityCandela,
+                    rangeM: entry.rangeM,
+                    innerConeDeg: entry.innerConeDeg,
+                    outerConeDeg: entry.outerConeDeg,
+                });
+    }
+    if (lightNodes.length) {
+        nodes.push(...lightNodes);
+        streamGroups.push({
+            id: 'group.lighting',
+            mode: 'eager',
+            priority: 1000,
+            dependencies: [],
+            estimatedMemoryMiB: 1,
+            cells: [{
+                    id: 'cell.lighting',
+                    bounds: { min: [...worldMin], max: [...worldMax] },
+                    nodes: lightNodes.map((node) => node.id),
+                }],
+        });
+    }
+    const mountDepth = 1 + Math.max(...mounts.map((mount) => mount.depth));
+    if (mountDepth > helix_manifest_1.HELIX_SCENE_CAPS.mountDepth) {
+        fail(`composed depth ${mountDepth} exceeds the cap of ${helix_manifest_1.HELIX_SCENE_CAPS.mountDepth}`);
+    }
+    // Default the budget so every mounted child can be resident at once. The
+    // runtime admits distance groups greedily until the budget is spent and then
+    // stops — a budget sized for one child renders one child and silently skips
+    // the rest, which reads as a hole in the world rather than as a limit.
+    const totalBudget = mounts.reduce((sum, mount) => sum + mount.budgetMiB, 0) + (lightNodes.length ? 1 : 0);
+    const memoryBudgetMiB = plan.memoryBudgetMiB ?? totalBudget;
+    if (memoryBudgetMiB < totalBudget) {
+        warnings.push(`memoryBudgetMiB ${memoryBudgetMiB} is below the ${totalBudget} MiB its ${mounts.length} mounts commit; the runtime will admit the nearest ones and skip the rest`);
+    }
+    if (memoryBudgetMiB > 2048) {
+        fail(`memoryBudgetMiB ${memoryBudgetMiB} exceeds the 2048 MiB profile cap; mount fewer children directly, or group them behind intermediate Scenes`);
+    }
+    // MAX_RESIDENT_MOUNTS in the web runtime. The format allows 64 mounts per
+    // document and the runtime keeps 8 of them live, so a 9th does not fail — it
+    // renders a world with a section missing. That is a hole hiding behind a
+    // plausible cap, so refuse it here instead of publishing it: the cap is
+    // per-streamer, and grouping children behind intermediate Scenes gets round
+    // it completely (8 intermediates x 8 children = 64 sections, all resident).
+    if (mounts.length > MAX_RESIDENT_MOUNTS) {
+        fail(`${mounts.length} mounts in one document: the web runtime keeps only the nearest ${MAX_RESIDENT_MOUNTS} live, so ${mounts.length - MAX_RESIDENT_MOUNTS} section(s) would be missing from the published world. Group them behind intermediate Scenes — the resident cap is per document, so a two-level tree carries all of them.`);
+    }
+    // Reach far enough that every mounted child is a candidate from anywhere
+    // inside the composed footprint; residency is then decided by the budget and
+    // by each child's own internal cell streaming, not by the parent's radius.
+    const span = [
+        worldMax[0] - worldMin[0],
+        worldMax[1] - worldMin[1],
+        worldMax[2] - worldMin[2],
+    ];
+    const streamRadiusM = plan.streamRadiusM ?? Math.max(1, Math.ceil(Math.hypot(span[0], span[1], span[2])));
+    // The parent owns the renderer, so a mounted child's `web.three-renderer/1`
+    // hints are ignored. Without them the web runtime adds no ambient or
+    // hemisphere term and every surface facing away from the sun renders black —
+    // a composed world that declares none looks broken rather than dark. Inherit
+    // the first child's, since the children were compiled together, and target no
+    // nodes: the parent has no lights of its own to configure.
+    //
+    // "Take the first child's" is only safe while the children AGREE, and they
+    // agree because a set compiled in one run is byte-identical by construction —
+    // a property of that set, not a rule. Children compiled at different times or
+    // with different flags can disagree, and then this silently picks one child's
+    // lighting for the whole world, which is a change nobody can attribute. So
+    // check rather than assume.
+    const hintSets = children
+        .map((child) => child.scene.runtimeExtensions.find((extension) => extension.runtime === 'web' && extension.extension === 'web.three-renderer/1'))
+        .filter((extension) => extension !== undefined);
+    const inherited = hintSets[0];
+    const disagreeing = children.filter((child, index) => {
+        const hints = hintSets[index];
+        if (!inherited || !hints)
+            return false;
+        return JSON.stringify(hints.parameters) !== JSON.stringify(inherited.parameters);
+    });
+    if (disagreeing.length) {
+        warnings.push(`web.three-renderer/1 hints differ across children (${disagreeing
+            .map((child) => `${child.scene.id}@${child.scene.revision}`)
+            .join(', ')} disagree with ${inherited?.id}); the composition takes one child's lighting for the whole world`);
+    }
+    const runtimeExtensions = plan.runtimeExtensions ??
+        (inherited
+            ? [{ ...inherited, id: 'ext.web.three-renderer', targetNodes: [], required: false, fallback: 'portable' }]
+            : []);
+    if (!runtimeExtensions.length) {
+        warnings.push('no web.three-renderer/1 hints: this composition has no ambient or hemisphere term and unlit faces will render black');
+    }
+    const spawn = plan.spawn ?? {
+        position: [
+            (worldMin[0] + worldMax[0]) / 2,
+            worldMin[1],
+            (worldMin[2] + worldMax[2]) / 2,
+        ],
+    };
+    const scene = {
+        format: helix_manifest_1.HELIX_SCENE_FORMAT,
+        version: helix_manifest_1.HELIX_SCENE_VERSION,
+        id: plan.sceneId,
+        revision: plan.revision,
+        integrity: { sha256: '' },
+        title: plan.title,
+        units: 'meters',
+        coordinateSystem: { handedness: 'right', up: '+Y', forward: '-Z' },
+        profiles: {
+            [profileId]: {
+                scene: rootId,
+                kind: 'world',
+                persistence: 'session',
+                // The World-build service refuses anything else until the runtime
+                // carries an authenticated World room identity.
+                maxPlayers: 1,
+                overrideAuthority: 'none',
+                runtimePolicy: {
+                    memoryBudgetMiB,
+                    streamRadiusM,
+                    allowSurfaceOverrides: false,
+                    allowItemPlacement: false,
+                },
+            },
+        },
+        scenes: [
+            {
+                id: rootId,
+                nodes: nodes.map((node) => node.id),
+                streamGroups: streamGroups.map((group) => group.id),
+            },
+        ],
+        resources: [],
+        nodes,
+        itemDefinitions: [],
+        itemInstances: [],
+        mounts,
+        mountDepth,
+        terrain: { kind: 'none' },
+        // A Scene with no environment renders a flat black sky, and a correct frame
+        // then looks broken. A composed parent owns the sky for the whole tree —
+        // a mounted child's environment is not read.
+        environment: {
+            background: true,
+            intensityScale: 1,
+            rotationYDeg: 0,
+            exposureEV100: 0,
+            fallbackColor: '#8aa4b8',
+            required: false,
+            ...(plan.environment ?? {}),
+        },
+        lights: authoredLights,
+        spawns: [
+            {
+                id: 'spawn.main',
+                position: spawn.position,
+                rotation: spawn.rotation ?? [0, 0, 0, 1],
+                profileAccess: [profileId],
+                clearanceRadiusM: spawn.clearanceRadiusM ?? 0.45,
+                clearanceHeightM: spawn.clearanceHeightM ?? 1.9,
+            },
+        ],
+        collision: { sets: [] },
+        navigation: {
+            walkableSurfaces: [],
+            agent: { radiusM: 0.35, heightM: 1.8, stepHeightM: 0.35, maxSlopeDeg: 45 },
+            navmesh: null,
+            fallback: 'physics-walkability',
+        },
+        placement: {
+            bounds: { min: worldMin, max: worldMax },
+            maxItemInstances: 0,
+            snapGridM: 0.25,
+            allowedProfiles: [],
+        },
+        surfaces: [],
+        materials: [],
+        behaviors: [],
+        streamGroups,
+        capabilities: {
+            required: [MOUNT_CAPABILITY, ...(authoredLights.length ? ['lighting.punctual/1'] : [])],
+            optional: [],
+        },
+        runtimeExtensions,
+        adapters: { unreal: helix_manifest_1.HELIX_TO_UNREAL_ADAPTER },
+    };
+    scene.integrity = { sha256: (0, helix_manifest_1.computeSceneDocumentIntegrity)(scene) };
+    // Compact, not pretty. Whitespace is ~52% of a pretty-printed document's
+    // bytes and is not part of the integrity hash, so indenting halves what fits
+    // under the 1 MiB cap in exchange for nothing.
+    const sceneBytes = Buffer.byteLength(JSON.stringify(scene), 'utf8');
+    // The same gate the backend runs. Behaviors are impossible here (the array is
+    // empty by construction), so refusing every signature is the honest verifier.
+    const validation = (0, helix_manifest_1.validateSceneDocumentForPublication)(scene, {
+        verifyBehaviorImplementationSignature: () => false,
+    });
+    if (!validation.valid) {
+        fail(`composed Scene is not publishable: ${validation.errors.join('; ')}`);
+    }
+    return {
+        scene,
+        sceneBytes,
+        mounts: summary,
+        mountDepth,
+        memoryBudgetMiB,
+        streamRadiusM,
+        bounds: { min: worldMin, max: worldMax },
+        warnings,
+    };
+}
+function padBounds(bounds, padM) {
+    if (!(padM >= 0))
+        fail(`padM must be zero or more, got ${padM}`);
+    return {
+        min: [bounds.min[0] - padM, bounds.min[1] - padM, bounds.min[2] - padM],
+        max: [bounds.max[0] + padM, bounds.max[1] + padM, bounds.max[2] + padM],
+    };
+}
+/**
+ * Resolve every child, compose the parent, and write a package directory that
+ * `scene-source publish` accepts as-is.
+ */
+async function composeMountsPackage(input) {
+    const profileId = input.plan.profile ?? 'world';
+    const children = [];
+    for (const entry of input.plan.mounts) {
+        children.push(await resolveChildScene(entry, {
+            defaultProfile: profileId,
+            ...(input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}),
+        }));
+    }
+    const composed = composeMountedScene(input.plan, children);
+    const outputDir = (0, node_path_1.resolve)(input.outputDir);
+    await (0, promises_1.mkdir)(outputDir, { recursive: true });
+    await (0, promises_1.writeFile)((0, node_path_1.join)(outputDir, SCENE_DOCUMENT_FILENAME), JSON.stringify(composed.scene), 'utf8');
+    await (0, promises_1.writeFile)((0, node_path_1.join)(outputDir, IMPORT_RECEIPT_FILENAME), JSON.stringify(composedReceipt(input.plan, composed), null, 2), 'utf8');
+    return { ...composed, outputDir };
+}
+function composedReceipt(plan, composed) {
+    return {
+        schemaVersion: 'helix.scene-source-conversion/1',
+        kind: 'mounted-scene-composition/1',
+        sourceId: plan.sceneId,
+        // A composition converts nothing; its source is the set of child digests it
+        // pins, so hash those rather than inventing a file hash for bytes that do
+        // not exist.
+        originalSha256: (0, node_crypto_1.createHash)('sha256')
+            .update(composed.mounts.map((mount) => mount.sha256).join('\n'))
+            .digest('hex'),
+        attribution: {
+            license: plan.attribution.license,
+            licenseUrl: plan.attribution.licenseUrl,
+            creator: plan.attribution.creator,
+            title: plan.attribution.title ?? plan.title,
+            url: plan.attribution.url,
+            changes: 'HELIX composed already-published Scene documents by pinning each one by content hash in mounts[] and placing it with a scene.mount node component.',
+        },
+        rights: {
+            licenseClass: plan.attribution.license.toLowerCase() === 'cc0'
+                ? 'open-public-domain'
+                : 'open-all-rights-reserved',
+            accessControlChangesLicense: false,
+            additionalRestrictions: 'none',
+            drm: 'not-permitted',
+        },
+        conversion: {
+            geometry: 'none — this document carries no geometry, only pinned child Scenes',
+            materials: 'inherited from each mounted child',
+            normalMaps: 'inherited from each mounted child',
+            orm: 'inherited from each mounted child',
+        },
+        unsupported: [],
+        // The publication gate wants evidence of what this package contains. A
+        // composition contains pins, so it names them; `outputs.scene` is its own
+        // sealed identity.
+        outputs: {
+            scene: { id: composed.scene.id, integritySha256: composed.scene.integrity.sha256 },
+            mounts: composed.mounts.map((mount) => ({
+                id: mount.id,
+                scene: mount.scene,
+                revision: mount.revision,
+                sha256: mount.sha256,
+            })),
+        },
+        composition: {
+            mountDepth: composed.mountDepth,
+            memoryBudgetMiB: composed.memoryBudgetMiB,
+            streamRadiusM: composed.streamRadiusM,
+            bounds: composed.bounds,
+            mounts: composed.mounts,
+        },
+    };
+}
+async function readComposePlan(path) {
+    const resolved = (0, node_path_1.resolve)(path);
+    let parsed;
+    try {
+        parsed = JSON.parse(await (0, promises_1.readFile)(resolved, 'utf8'));
+    }
+    catch (err) {
+        fail(`${resolved} is not readable JSON (${String(err)})`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        fail(`${resolved} must contain a compose plan object`);
+    }
+    const plan = parsed;
+    for (const field of ['sceneId', 'revision', 'title']) {
+        if (typeof plan[field] !== 'string' || !plan[field])
+            fail(`${resolved}: "${field}" is required`);
+    }
+    if (!Array.isArray(plan.mounts) || !plan.mounts.length) {
+        fail(`${resolved}: "mounts" must be a non-empty array`);
+    }
+    const attribution = plan.attribution;
+    if (!attribution ||
+        typeof attribution.license !== 'string' ||
+        typeof attribution.licenseUrl !== 'string' ||
+        typeof attribution.creator !== 'string' ||
+        typeof attribution.url !== 'string') {
+        fail(`${resolved}: "attribution" needs license, licenseUrl, creator and url`);
+    }
+    return plan;
+}
+//# sourceMappingURL=composeMounts.js.map