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

package/dist/sceneImport/proxy.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXY_TARGET_MISS_TOLERANCE = exports.PROXY_MIN_DETAIL_BYTES = exports.PROXY_MIN_DETAIL_TRIANGLES = exports.PROXY_KEEP_MAX_TRIANGLE_RATIO = void 0;
+exports.artifactFromDocument = artifactFromDocument;
+exports.shouldAttemptWeldedFallback = shouldAttemptWeldedFallback;
+exports.simplifiedProxyArtifact = simplifiedProxyArtifact;
+exports.summarizeProxyReductions = summarizeProxyReductions;
+exports.proxyReductionWarnings = proxyReductionWarnings;
+const node_crypto_1 = require("node:crypto");
+const core_1 = require("@gltf-transform/core");
+const functions_1 = require("@gltf-transform/functions");
+const meshoptimizer_1 = require("meshoptimizer");
+const report_1 = require("../character/stages/report");
+const simplifyMesh_1 = require("../character/stages/simplifyMesh");
+/**
+ * Collision-proxy derivation shared by every intake format.
+ *
+ * Lives apart from the FBX compiler so OBJ/GLB-only packs never load the
+ * ESM-only three.js loaders this repo cannot import under Jest: proxies are
+ * pure glTF-Transform work — flat default material, meshopt simplification,
+ * prune — independent of where the detail GLB came from.
+ */
+async function artifactFromDocument(io, document, filename, bounds) {
+    const bytes = Buffer.from(await io.writeBinary(document));
+    return {
+        filename,
+        bytes,
+        contentSha256: (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex'),
+        bounds,
+        summary: {
+            triangles: (0, report_1.countTriangles)(document),
+            materials: document.getRoot().listMaterials().length,
+            textures: document.getRoot().listTextures().length,
+            nodes: document.getRoot().listNodes().length,
+        },
+    };
+}
+/**
+ * A proxy costs a whole resource FILE out of the build endpoint's 199-file
+ * budget, so a proxy is only worth emitting when it is meaningfully smaller
+ * than the detail it stands in for. Measured over the QA packs and the Pacifica
+ * mall corpus, a proxy either lands at <= 27% of detail triangles (the welded
+ * route hits its target exactly) or at 100% (meshopt floored on attribute
+ * seams) — there is no observed middle ground, so a 70% gate separates the two
+ * populations with room to spare rather than sitting on top of either.
+ */
+exports.PROXY_KEEP_MAX_TRIANGLE_RATIO = 0.7;
+/**
+ * Below this, the DETAIL mesh already is the cheap level: a 30-triangle,
+ * 3.8 KB prop cannot pay back the file slot, the extra fetch, and the LOD pop
+ * its proxy would cost. Both floors must be undershot — a small-triangle mesh
+ * carrying a big texture payload still benefits from a geometry-only proxy.
+ */
+exports.PROXY_MIN_DETAIL_TRIANGLES = 512;
+exports.PROXY_MIN_DETAIL_BYTES = 64 * 1024;
+/**
+ * How far the attribute-preserving pass may miss its triangle target before the
+ * seam-breaking fallback is attempted.
+ *
+ * The first cut of this gate asked the WRONG QUESTION. It fired the fallback on
+ * `triangles > detail * PROXY_KEEP_MAX_TRIANGLE_RATIO` — a RELATIVE test against
+ * the keep gate — so a mesh that reduced to 66.9% of its source slipped under
+ * 0.7 and the fallback was never attempted, even though it had missed its own
+ * target by 13x. The Pacifica mall's SM_Generator is exactly that shape: 67,139
+ * triangles against a 3,403 target, floored at 44,929 by attribute seams and
+ * accepted as a success. Routed through the fallback it reaches 3,398.
+ *
+ * A miss is measured against the TARGET, because that is what the caller asked
+ * for. The tolerance keeps the expensive pass off meshes that essentially landed
+ * (a 3,500-triangle result against a 3,403 target is not seam-blocked); anything
+ * beyond half again its target is presumed stuck and worth a second attempt.
+ */
+exports.PROXY_TARGET_MISS_TOLERANCE = 1.5;
+/**
+ * Should the seam-breaking fallback be attempted after the attribute-preserving
+ * pass returned `candidateTriangles`?
+ *
+ * Kept as a pure predicate because the ORIGINAL BUG WAS IN THIS DECISION, not in
+ * either simplification route: asking only whether the candidate sat above the
+ * keep ratio let a mesh that missed its target 13-fold count as a success. Both
+ * questions have to be asked — did it reach what the caller asked for, and did it
+ * move at all relative to the source.
+ */
+function shouldAttemptWeldedFallback(input) {
+    const missedTarget = input.candidateTriangles > input.targetTriangles * exports.PROXY_TARGET_MISS_TOLERANCE;
+    const barelyMoved = input.candidateTriangles > input.detailTriangles * exports.PROXY_KEEP_MAX_TRIANGLE_RATIO;
+    return missedTarget || barelyMoved;
+}
+function countPrimitives(document) {
+    let total = 0;
+    for (const mesh of document.getRoot().listMeshes())
+        total += mesh.listPrimitives().length;
+    return total;
+}
+function silence(document) {
+    document.setLogger(new core_1.Logger(core_1.Logger.Verbosity.SILENT));
+    return document;
+}
+function applyProxyMaterial(document) {
+    const fallback = document
+        .createMaterial('HELIX_Default_Proxy')
+        .setBaseColorFactor([0.65, 0.67, 0.7, 1])
+        .setRoughnessFactor(1)
+        .setMetallicFactor(0);
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives())
+            primitive.setMaterial(fallback);
+    }
+}
+/**
+ * Position-welded simplification for geometry meshopt cannot touch.
+ *
+ * meshopt ALWAYS preserves attribute-seam vertices (see simplifyMesh.ts). A
+ * flat-shaded kitbash prop — a stack of boxes, every vertex split three ways by
+ * its face normal — is ENTIRELY seam vertices, so the attribute-preserving pass
+ * floors at 100% no matter the error budget. Three moves break that floor, and
+ * all three are legal on a proxy in a way they never are on a character:
+ *
+ *   1. join every mesh/primitive into ONE primitive (the proxy already carries a
+ *      single flat material, so there is nothing to keep apart) — this alone
+ *      collapses 123 draw calls to 1 on the QA pack's kitbash props;
+ *   2. DROP every attribute except POSITION — a grey untextured proxy has no UVs
+ *      worth protecting and its per-face normals ARE the seams doing the
+ *      flooring. glTF primitives without NORMAL render flat-shaded, which is
+ *      what a proxy wants anyway;
+ *   3. weld by position and simplify against a wide error budget.
+ *
+ * The trade is explicit: normals and UVs are discarded. On collision/far-LOD
+ * geometry that costs nothing visible — the mesh is one flat colour past the
+ * detail range — and it buys the reduction that makes the second LOD level
+ * worth its file slot at all.
+ */
+async function positionWeldedProxy(document, targetTriangles) {
+    await meshoptimizer_1.MeshoptSimplifier.ready;
+    await document.transform((0, functions_1.join)({ keepNamed: false }));
+    for (const mesh of document.getRoot().listMeshes()) {
+        const triangles = mesh.listPrimitives().filter((primitive) => primitive.getMode() === 4);
+        if (triangles.length < 2)
+            continue;
+        // joinPrimitives requires a shared MATERIAL as well as a shared mode, and
+        // filtering on mode alone was enough only while every primitive in a mesh
+        // happened to carry the same material. A mesh with real per-slot textures
+        // has several, and the call then throws "Requires >=2 Primitives, sharing
+        // the same Material and Mode" — a hard compile failure, from geometry that
+        // is about to have every attribute except POSITION stripped anyway.
+        //
+        // Grouping by material is a no-op for the single-material case (one group,
+        // same join, byte-identical output) and joins per material otherwise.
+        // The compatibility contract is material + mode + ATTRIBUTE SET + indexed-
+        // ness, so the key has to carry all of it. Grouping on material alone still
+        // throws the moment one primitive has TEXCOORD_0 and its neighbour does not.
+        const materialIndex = new Map();
+        const byCompatibility = new Map();
+        for (const primitive of triangles) {
+            const material = primitive.getMaterial() ?? null;
+            if (!materialIndex.has(material))
+                materialIndex.set(material, materialIndex.size);
+            const key = [
+                materialIndex.get(material),
+                [...primitive.listSemantics()].sort().join(','),
+                primitive.getIndices() ? 'indexed' : 'nonindexed',
+            ].join('|');
+            const group = byCompatibility.get(key);
+            if (group)
+                group.push(primitive);
+            else
+                byCompatibility.set(key, [primitive]);
+        }
+        for (const group of byCompatibility.values()) {
+            if (group.length < 2)
+                continue;
+            const joined = (0, functions_1.joinPrimitives)(group);
+            for (const primitive of group)
+                mesh.removePrimitive(primitive);
+            mesh.addPrimitive(joined);
+        }
+    }
+    for (const mesh of document.getRoot().listMeshes()) {
+        for (const primitive of mesh.listPrimitives()) {
+            for (const semantic of primitive.listSemantics()) {
+                if (semantic !== 'POSITION')
+                    primitive.setAttribute(semantic, null);
+            }
+        }
+    }
+    await document.transform((0, functions_1.weld)());
+    let current = (0, report_1.countTriangles)(document);
+    for (let attempt = 0; attempt < 6 && current > targetTriangles; attempt += 1) {
+        await document.transform((0, functions_1.simplify)({
+            simplifier: meshoptimizer_1.MeshoptSimplifier,
+            ratio: targetTriangles / current,
+            error: 0.4,
+            lockBorder: false,
+        }));
+        const after = (0, report_1.countTriangles)(document);
+        if (after >= current)
+            break;
+        current = after;
+    }
+}
+function proxyExtras() {
+    return {
+        helixSource: {
+            conversion: {
+                geometry: 'per-asset meshopt-simplified collision proxy',
+                materials: 'geometry-only HELIX default material proxy',
+                normalMaps: 'not represented in the proxy',
+                orm: 'not represented in the proxy',
+            },
+        },
+    };
+}
+/**
+ * Derives the collision proxy from one compiled detail artifact: flat default
+ * material, meshopt-simplified, pruned — and then MEASURED against the detail
+ * it replaces. A proxy that did not actually get smaller is not emitted; the
+ * caller declares a single-level LOD for that mesh instead, because one real
+ * level beats two identical ones and costs half the file budget.
+ */
+async function simplifiedProxyArtifact(io, detail, name, targetTriangles) {
+    const detailDocument = silence(await io.readBinary(new Uint8Array(detail.bytes)));
+    const detailTriangles = (0, report_1.countTriangles)(detailDocument);
+    const detailPrimitives = countPrimitives(detailDocument);
+    const base = {
+        name,
+        detailTriangles,
+        detailPrimitives,
+        detailBytes: detail.bytes.length,
+    };
+    const drop = (decision, measured) => ({
+        proxy: null,
+        reduction: {
+            ...base,
+            targetTriangles: null,
+            proxyTriangles: null,
+            proxyPrimitives: null,
+            proxyBytes: null,
+            triangleRatio: null,
+            byteRatio: null,
+            strategy: 'none',
+            ...measured,
+            kept: false,
+            decision,
+        },
+    });
+    if (targetTriangles === undefined &&
+        detailTriangles < exports.PROXY_MIN_DETAIL_TRIANGLES &&
+        detail.bytes.length < exports.PROXY_MIN_DETAIL_BYTES) {
+        return drop('below-complexity-floor');
+    }
+    const target = Math.min(60_000, Math.max(64, targetTriangles ?? Math.ceil(detailTriangles / 8)));
+    const build = async (strategy) => {
+        const document = silence(await io.readBinary(new Uint8Array(detail.bytes)));
+        applyProxyMaterial(document);
+        if (strategy === 'attribute-preserving') {
+            await (0, simplifyMesh_1.simplifyToTarget)(document, target, 0.08, false);
+            await document.transform((0, functions_1.prune)());
+        }
+        else {
+            await positionWeldedProxy(document, target);
+            await document.transform((0, functions_1.prune)(), (0, functions_1.dedup)());
+        }
+        document.getRoot().setExtras(proxyExtras());
+        const artifact = await artifactFromDocument(io, document, `${name}.proxy.glb`, detail.bounds);
+        return { artifact, triangles: (0, report_1.countTriangles)(document), primitives: countPrimitives(document) };
+    };
+    // Pass 1 preserves normals and UVs, so it is preferred whenever it actually
+    // reaches the target. Pass 2 is the seam-breaking fallback for geometry it
+    // cannot move — attempted whenever pass 1 MISSED THE TARGET by more than the
+    // tolerance, or is so close to the source that it plainly floored. Testing
+    // only the latter let a 66.9% result count as success while missing its
+    // target 13-fold; see PROXY_TARGET_MISS_TOLERANCE.
+    let strategy = 'attribute-preserving';
+    let candidate = await build(strategy);
+    if (shouldAttemptWeldedFallback({
+        candidateTriangles: candidate.triangles,
+        detailTriangles,
+        targetTriangles: target,
+    })) {
+        const welded = await build('position-welded');
+        if (welded.triangles < candidate.triangles) {
+            candidate = welded;
+            strategy = 'position-welded';
+        }
+    }
+    const measured = {
+        targetTriangles: target,
+        proxyTriangles: candidate.triangles,
+        proxyPrimitives: candidate.primitives,
+        proxyBytes: candidate.artifact.bytes.length,
+        triangleRatio: detailTriangles > 0 ? candidate.triangles / detailTriangles : 1,
+        byteRatio: candidate.artifact.bytes.length / Math.max(1, detail.bytes.length),
+        strategy,
+    };
+    if (measured.triangleRatio > exports.PROXY_KEEP_MAX_TRIANGLE_RATIO) {
+        return drop('no-triangle-reduction', measured);
+    }
+    if (candidate.artifact.bytes.length >= detail.bytes.length) {
+        return drop('not-smaller-in-bytes', measured);
+    }
+    return { proxy: candidate.artifact, reduction: { ...base, ...measured, kept: true, decision: 'kept' } };
+}
+/** One-line compile summary over every mesh's proxy decision. */
+function summarizeProxyReductions(reductions) {
+    const kept = reductions.filter((reduction) => reduction.kept);
+    const dropped = reductions.filter((reduction) => !reduction.kept);
+    const byReason = new Map();
+    for (const reduction of dropped) {
+        byReason.set(reduction.decision, (byReason.get(reduction.decision) ?? 0) + 1);
+    }
+    const averageRatio = kept.length
+        ? kept.reduce((sum, reduction) => sum + (reduction.triangleRatio ?? 1), 0) / kept.length
+        : 0;
+    const reasons = [...byReason]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([reason, count]) => `${count} ${reason}`)
+        .join(', ');
+    const keptPart = kept.length
+        ? `${kept.length} kept (avg ${(averageRatio * 100).toFixed(1)}% of detail tris)`
+        : '0 kept';
+    return `proxies: ${keptPart}, ${dropped.length} dropped${reasons ? ` (${reasons})` : ''}`;
+}
+/** Loud, per-NAMED-mesh warnings for every proxy that missed the reduction target. */
+function proxyReductionWarnings(reductions) {
+    return reductions
+        .filter((reduction) => !reduction.kept && reduction.decision !== 'below-complexity-floor')
+        .map((reduction) => `⚠ proxy for ${reduction.name} missed the reduction target (${reduction.decision}): ` +
+        `${reduction.detailTriangles} tris / ${reduction.detailBytes} B detail -> ` +
+        `${reduction.proxyTriangles ?? '-'} tris / ${reduction.proxyBytes ?? '-'} B proxy ` +
+        `via ${reduction.strategy} against a ${reduction.targetTriangles ?? '-'}-triangle target ` +
+        `(floored at ${((reduction.triangleRatio ?? 1) * 100).toFixed(1)}% of detail); ` +
+        `emitting a single-level LOD instead`);
+}
+//# sourceMappingURL=proxy.js.map

package/dist/sceneImport/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/sceneImport/proxy.ts"],"names":[],"mappings":"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"}

package/dist/sceneImport/publish.d.ts

@@ -0,0 +1,47 @@
+export type SceneV2WorldBuildInput = {
+    worldId: string;
+    profileId: string;
+    scene: Buffer;
+    resources: Array<{
+        path: string;
+        bytes: Buffer;
+        mimeType: string;
+    }>;
+    /** How many child Scenes this document mounts. Mounted geometry is theirs. */
+    mountCount?: number;
+    /** Zero-download render primitives carried directly by the Scene document. */
+    primitiveCount?: number;
+    contentRating: 'everyone' | 'teen' | 'mature';
+    supportsMobile: boolean;
+    requiresAuth: boolean;
+    visibility: 'private' | 'unlisted' | 'public';
+};
+export declare function validateSceneV2WorldBuildInput(input: SceneV2WorldBuildInput): void;
+export declare function assertSafeSceneResourcePath(path: string): void;
+export declare function sceneV2WorldBuildPath(worldId: string): string;
+export declare function buildSceneV2WorldForm(input: SceneV2WorldBuildInput): {
+    path: string;
+    form: import("undici-types").FormData;
+};
+export declare function createSceneV2DryRunReceipt(input: SceneV2WorldBuildInput): {
+    schemaVersion: string;
+    dryRun: boolean;
+    published: boolean;
+    authorizationRequired: boolean;
+    method: string;
+    path: string;
+    worldId: string;
+    profileId: string;
+    visibility: "public" | "unlisted" | "private";
+    sceneSha256: string;
+    resources: {
+        path: string;
+        mimeType: string;
+        bytes: number;
+        contentSha256: string;
+    }[];
+    note: string;
+};
+export declare function publishSceneV2World(api: {
+    postMultipart<T>(path: string, form: FormData): Promise<T>;
+}, input: SceneV2WorldBuildInput): Promise<unknown>;

package/dist/sceneImport/publish.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSceneV2WorldBuildInput = validateSceneV2WorldBuildInput;
+exports.assertSafeSceneResourcePath = assertSafeSceneResourcePath;
+exports.sceneV2WorldBuildPath = sceneV2WorldBuildPath;
+exports.buildSceneV2WorldForm = buildSceneV2WorldForm;
+exports.createSceneV2DryRunReceipt = createSceneV2DryRunReceipt;
+exports.publishSceneV2World = publishSceneV2World;
+const node_crypto_1 = require("node:crypto");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function validateSceneV2WorldBuildInput(input) {
+    if (!UUID.test(input.worldId))
+        throw new Error('World ID must be a UUID');
+    if (!input.profileId.trim())
+        throw new Error('profile ID is required');
+    if (!input.scene.length)
+        throw new Error('Scene document is empty');
+    // Corrected 2026-09-25 (P6 W2, ADR-0004): a Scene resource may no longer
+    // declare its geometry route as a Vault pin — the CLI's `vault-pin` command
+    // is gone (recent Worlds publish via continuum_release with zero Vault
+    // pins). A COMPOSED Scene may still declare no resources at all: its
+    // geometry lives in the child Scenes it mounts, each already published with
+    // its own resources. A semantic architectural Scene may go further still:
+    // render.primitive components ARE its geometry, so it legitimately has no
+    // resource table. What is still refused is a Scene with no geometry by any
+    // remaining route.
+    if (!input.resources.length && !(input.mountCount ?? 0) && !(input.primitiveCount ?? 0)) {
+        throw new Error('at least one Scene geometry route is required: a bundle file, mounted Scene or render primitive');
+    }
+    const seen = new Set();
+    for (const resource of input.resources) {
+        assertSafeSceneResourcePath(resource.path);
+        if (seen.has(resource.path))
+            throw new Error(`duplicate Scene resource path: ${resource.path}`);
+        seen.add(resource.path);
+        if (!resource.bytes.length)
+            throw new Error(`Scene resource is empty: ${resource.path}`);
+        if (!resource.mimeType)
+            throw new Error(`Scene resource MIME type is required: ${resource.path}`);
+    }
+}
+function assertSafeSceneResourcePath(path) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(path) || path.includes('..') || path.includes('\\')) {
+        throw new Error(`unsafe Scene resource path: ${path}`);
+    }
+}
+function sceneV2WorldBuildPath(worldId) {
+    return `/api/v1/instant-worlds/${encodeURIComponent(worldId)}/builds/scene-v2`;
+}
+function buildSceneV2WorldForm(input) {
+    validateSceneV2WorldBuildInput(input);
+    const form = new FormData();
+    form.append('payload', JSON.stringify({
+        profileId: input.profileId.trim(),
+        resourcePaths: input.resources.map((resource) => resource.path),
+        contentRating: input.contentRating,
+        supportsMobile: input.supportsMobile,
+        requiresAuth: input.requiresAuth,
+        visibility: input.visibility,
+    }));
+    form.append('scene', new Blob([new Uint8Array(input.scene)], {
+        type: 'application/vnd.helix.scene+json;version=2',
+    }), 'scene.helix-scene.json');
+    for (const resource of input.resources) {
+        form.append('resources', new Blob([new Uint8Array(resource.bytes)], { type: resource.mimeType }), resource.path.split('/').pop());
+    }
+    return {
+        path: sceneV2WorldBuildPath(input.worldId),
+        form,
+    };
+}
+function createSceneV2DryRunReceipt(input) {
+    validateSceneV2WorldBuildInput(input);
+    return {
+        schemaVersion: 'helix.scene-v2-world-build-dry-run/1',
+        dryRun: true,
+        published: false,
+        authorizationRequired: true,
+        method: 'POST',
+        path: sceneV2WorldBuildPath(input.worldId),
+        worldId: input.worldId,
+        profileId: input.profileId,
+        visibility: input.visibility,
+        sceneSha256: (0, node_crypto_1.createHash)('sha256').update(input.scene).digest('hex'),
+        resources: input.resources.map((resource) => ({
+            path: resource.path,
+            mimeType: resource.mimeType,
+            bytes: resource.bytes.length,
+            contentSha256: (0, node_crypto_1.createHash)('sha256').update(resource.bytes).digest('hex'),
+        })),
+        note: 'No bytes were uploaded. Publishing requires backend private-pin entitlement and live authorization receipts.',
+    };
+}
+async function publishSceneV2World(api, input) {
+    const request = buildSceneV2WorldForm(input);
+    return api.postMultipart(request.path, request.form);
+}
+//# sourceMappingURL=publish.js.map

package/dist/sceneImport/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../src/sceneImport/publish.ts"],"names":[],"mappings":"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"}

package/dist/sceneImport/semantic.d.ts

@@ -0,0 +1,75 @@
+import { type ContinuumObjectReference, type ContinuumPackageVersionReference, type ContinuumSceneBounds, type ContinuumSceneDocument, type ContinuumSceneResidency, type ContinuumSceneRole, type ContinuumSceneTransform } from '@hypersoniclabs/helix-manifest';
+import { type MaterialMatch, type SharedMaterialBindingInput, type SourceMaterialDescription } from './materials';
+export declare const NATIVE_SCENE_CONVERSION_CONFIDENCE = 0.95;
+export declare const SOURCE_SCENE_IMPORT_BUDGETS: {
+    readonly actors: 20000;
+    readonly materials: 4096;
+    readonly materialSlotsPerActor: 64;
+    readonly totalMaterialSlots: 100000;
+    readonly hierarchyDepth: 32;
+    readonly stringCharacters: 5000000;
+    readonly stringLength: 512;
+    readonly totalInputUnits: 1000000;
+};
+export type SourceSceneMaterial = {
+    id: string;
+    description: SourceMaterialDescription;
+    sourcePackage: ContinuumPackageVersionReference;
+    binding?: Omit<SharedMaterialBindingInput, 'material' | 'slot'>;
+};
+export type SourceNativeCandidate = Record<string, unknown> & {
+    type: 'wall' | 'floor' | 'ceiling' | 'opening' | 'door' | 'window' | 'stairs' | 'primitive' | 'foliage' | 'light' | 'portal' | 'gameplay-anchor' | 'child-scene' | 'terrain' | 'placements';
+};
+export type SourceSceneActor = {
+    id: string;
+    parentId?: string;
+    kind: 'building' | 'group' | 'level' | 'space' | SourceNativeCandidate['type'] | 'unknown';
+    confidence: number;
+    candidate?: SourceNativeCandidate;
+    transform?: ContinuumSceneTransform;
+    bounds?: ContinuumSceneBounds;
+    mesh?: ContinuumObjectReference;
+    proxy?: ContinuumObjectReference;
+    collider?: ContinuumObjectReference;
+    materialSlots?: Record<string, string>;
+    role?: ContinuumSceneRole;
+    collision?: boolean;
+    residency?: ContinuumSceneResidency;
+    sourceId?: string;
+};
+export type SourceSceneMap = {
+    id: string;
+    title: string;
+    materials: SourceSceneMaterial[];
+    canonicalMaterialPackages: Readonly<Record<string, ContinuumPackageVersionReference>>;
+    actors: SourceSceneActor[];
+};
+export type SourceSceneImportReceipt = {
+    schema: 'helix.creator.scene-import-receipt/1';
+    conversions: Array<{
+        actorId: string;
+        action: 'native' | 'mesh-backed' | 'container';
+        confidence: number;
+        reason: string;
+        sourceMeshCid?: string;
+    }>;
+    materials: Array<{
+        sourceMaterialId: string;
+        action: MaterialMatch['action'];
+        confidence: number;
+        selectedPackageId: string;
+        preserveSourceRendition: boolean;
+        reason: string;
+    }>;
+};
+export type SourceSceneImportResult = {
+    document: ContinuumSceneDocument;
+    receipt: SourceSceneImportReceipt;
+};
+/**
+ * Convert an already-inventoried source map into the canonical semantic tree.
+ * Classification is deliberately caller-visible: only candidates at or above
+ * the proof threshold become native elements, and even those retain the exact
+ * source mesh as a fallback object when one exists.
+ */
+export declare function importSourceSceneMap(input: SourceSceneMap): SourceSceneImportResult;