@aura3d/engine 1.0.2 → 1.0.5

package/dist/aura3d-cli/index.js

@@ -38,10 +38,19 @@ export function addAsset(options) {
         hash: `sha256-${hash}`,
         sizeBytes: statSync(sourcePath).size,
         bounds: inspection.bounds,
+        boundsMetadata: inspection.boundsMetadata,
         materials: inspection.materials,
+        materialMetadata: inspection.materialMetadata,
         animations: inspection.animations,
+        animationMetadata: inspection.animation,
+        humanoid: inspection.humanoid,
+        skeleton: inspection.skeleton,
+        morphTargets: inspection.morphTargets,
+        provenance: createAssetProvenance(projectDir, sourcePath, options, inspection.provenance),
         textures: inspection.textures,
         dependencies: inspection.dependencies,
+        orientation: inspection.orientation,
+        nodeNames: inspection.nodeNames,
         thumbnailUrl,
         warnings: createAssetWarnings(sourcePath, inspection)
     };
@@ -91,14 +100,55 @@ export function scanAssets(options) {
         messages: ["No supported assets found."]
     };
 }
+export function inspectAsset(options) {
+    const projectDir = resolve(options.projectDir ?? process.cwd());
+    const sourcePath = resolve(projectDir, options.file);
+    if (!existsSync(sourcePath)) {
+        throw new Error(`Aura3D assets inspect failed: "${options.file}" does not exist.`);
+    }
+    const format = extname(sourcePath).slice(1).toLowerCase();
+    const inspection = inspectAssetFile(sourcePath, format);
+    const warnings = createAssetWarnings(sourcePath, inspection);
+    return {
+        ok: warnings.length === 0,
+        schema: "aura3d.asset-inspection/1.0",
+        file: normalizeRelativePath(relative(projectDir, sourcePath)),
+        format,
+        sizeBytes: statSync(sourcePath).size,
+        bounds: inspection.bounds,
+        boundsMetadata: inspection.boundsMetadata,
+        materials: inspection.materials,
+        materialMetadata: inspection.materialMetadata,
+        animations: inspection.animations,
+        ...(options.animation ? { animation: inspection.animation } : {}),
+        ...(options.humanoid ? { humanoid: inspection.humanoid } : {}),
+        ...(options.skeleton ? { skeleton: inspection.skeleton } : {}),
+        ...(options.morphs ? { morphTargets: inspection.morphTargets } : {}),
+        ...(options.license ? { provenance: createAssetProvenance(projectDir, sourcePath, {}, inspection.provenance) } : {}),
+        textures: inspection.textures,
+        orientation: inspection.orientation,
+        nodeNames: inspection.nodeNames,
+        dependencies: inspection.dependencies,
+        warnings,
+        messages: warnings.length === 0 ? ["Asset inspection completed."] : warnings
+    };
+}
 export function validateAssets(options = {}) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
     const manifestPath = resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST);
     const manifestMissing = !existsSync(manifestPath);
-    const manifest = readAssetManifest(projectDir);
+    const sourceManifest = readAssetManifest(projectDir);
+    const manifest = filterAssetManifest(sourceManifest, options.assetIds);
+    const externalProvenance = readExternalProvenance(projectDir, options.provenanceFile);
     const failures = manifestMissing
         ? [`Missing ${DEFAULT_AURA_ASSET_MANIFEST}. Suggested fix: run aura3d assets add ./asset.glb --name product or aura3d assets scan ./assets.`]
         : [];
+    const missingAssetIds = findMissingAssetIds(sourceManifest, options.assetIds);
+    for (const id of missingAssetIds)
+        failures.push(`Requested asset "${id}" was not found in ${DEFAULT_AURA_ASSET_MANIFEST}.`);
+    if (options.provenanceFile && !existsSync(resolve(projectDir, options.provenanceFile))) {
+        failures.push(`Missing asset provenance evidence file: ${options.provenanceFile}`);
+    }
     const warnings = [];
     for (const asset of manifest.assets) {
         const outputPath = resolve(projectDir, asset.outputPath);
@@ -109,6 +159,13 @@ export function validateAssets(options = {}) {
         const actualHash = `sha256-${hashFile(outputPath)}`;
         if (actualHash !== asset.hash)
             failures.push(`Hash mismatch for "${asset.id}": expected ${asset.hash}, found ${actualHash}`);
+        const provenance = resolveAssetProvenance(asset, externalProvenance);
+        if (options.noPlaceholders && isPlaceholderAsset(asset, provenance)) {
+            failures.push(`Placeholder asset is not allowed in strict release validation: "${asset.id}". Replace it with a real typed asset and provenance.`);
+        }
+        if (options.requireLicense && !hasUsableLicenseEvidence(provenance)) {
+            failures.push(`Missing license/provenance evidence for "${asset.id}". Add it with assets add --license ... --source-url ... or pass --provenance <evidence.json>.`);
+        }
         warnings.push(...asset.warnings.map((warning) => `${asset.id}: ${warning}`));
         if (asset.format === "gltf") {
             for (const dependency of asset.dependencies ?? asset.textures) {
@@ -145,6 +202,22 @@ export function writeTypedAssets(projectDir, manifest = readAssetManifest(projec
             const metadata = {
                 materials: asset.materials,
                 animations: asset.animations,
+                animationClips: asset.animations,
+                animationMetadata: asset.animationMetadata ?? createReadinessAnimationMetadata(asset.animations),
+                humanoid: asset.humanoid?.humanoid ?? false,
+                humanoidStatus: asset.humanoid?.status ?? "unknown",
+                humanoidConfidence: asset.humanoid?.confidence ?? "low",
+                skeleton: asset.skeleton,
+                morphTargets: asset.morphTargets,
+                provenance: asset.provenance,
+                sourcePath: asset.source,
+                outputPath: asset.outputPath,
+                license: asset.provenance?.license,
+                author: asset.provenance?.author,
+                boundsMetadata: asset.boundsMetadata,
+                materialMetadata: asset.materialMetadata,
+                orientation: asset.orientation,
+                nodeNames: asset.nodeNames ?? [],
                 textures: asset.textures,
                 dependencies: asset.dependencies ?? [],
                 thumbnailUrl: asset.thumbnailUrl
@@ -228,6 +301,97 @@ export function checkDeploy(options = {}) {
         messages: failures.length === 0 ? ["Deploy check passed."] : failures
     };
 }
+export function validateGameAssets(options = {}) {
+    return validateAssetReadiness("game", options);
+}
+export function validateCartoonAssets(options = {}) {
+    return validateAssetReadiness("cartoon", options);
+}
+export function createCharacterAssemblyPlan(options) {
+    const projectDir = resolve(options.projectDir ?? process.cwd());
+    const manifest = readAssetManifest(projectDir);
+    const failures = [];
+    const warnings = [];
+    const output = normalizeRelativePath(options.output ?? `src/aura-character-${sanitizeAssetId(options.name)}.assembly.json`);
+    const bodyAsset = manifest.assets.find((asset) => asset.id === options.body);
+    if (!bodyAsset) {
+        failures.push(`Missing body asset "${options.body}". Add it first with aura3d assets add ./body.glb --name ${options.body}.`);
+    }
+    else if (bodyAsset.type !== "model") {
+        failures.push(`Body asset "${options.body}" must be a model asset, found ${bodyAsset.type}.`);
+    }
+    else if (bodyAsset.humanoid && !bodyAsset.humanoid.humanoid) {
+        warnings.push(`Body asset "${options.body}" has humanoid status "${bodyAsset.humanoid.status}"; character assembly can still compose parts, but acting and retargeting may be limited.`);
+    }
+    const resolvePart = (part) => {
+        const asset = manifest.assets.find((entry) => entry.id === part.asset);
+        if (!asset) {
+            failures.push(`Missing ${part.slot} part asset "${part.asset}".`);
+            return undefined;
+        }
+        if (asset.type !== "model")
+            warnings.push(`${part.slot}: "${part.asset}" is ${asset.type}; character assembly expects model parts for rig/attachment safety.`);
+        return {
+            slot: part.slot,
+            asset: part.asset,
+            url: asset.url,
+            type: asset.type,
+            format: asset.format,
+            animations: asset.animations,
+            humanoid: asset.humanoid,
+            attachTo: part.attachTo ?? defaultAttachPoint(part.slot)
+        };
+    };
+    const parts = (options.parts ?? []).map(resolvePart).filter((part) => Boolean(part));
+    const body = bodyAsset
+        ? {
+            slot: "body",
+            asset: bodyAsset.id,
+            url: bodyAsset.url,
+            type: bodyAsset.type,
+            format: bodyAsset.format,
+            animations: bodyAsset.animations,
+            humanoid: bodyAsset.humanoid,
+            attachTo: "root"
+        }
+        : {
+            slot: "body",
+            asset: options.body,
+            url: "",
+            type: "model",
+            format: "missing",
+            animations: [],
+            attachTo: "root"
+        };
+    const plan = {
+        schema: "aura3d.character-assembly/1.0",
+        name: options.name,
+        output,
+        scale: options.scale ?? 1,
+        body,
+        parts,
+        rules: {
+            normalizeScale: true,
+            facePositiveZ: true,
+            preserveTypedAssetReferences: true,
+            requireNamedAttachments: true
+        }
+    };
+    mkdirSync(dirname(resolve(projectDir, output)), { recursive: true });
+    writeFileSync(resolve(projectDir, output), `${JSON.stringify(plan, null, 2)}\n`);
+    return {
+        ok: failures.length === 0,
+        schema: "aura3d.character-assembly/1.0",
+        name: options.name,
+        output,
+        body,
+        parts,
+        validation: { failures, warnings },
+        messages: failures.length === 0
+            ? [`Wrote ${output}. Import typed assets from src/aura-assets.ts and compose with model(assets.${options.body}).`]
+            : failures
+    };
+}
 export function initAgentFiles(options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
     const targets = options.agent === "all" ? ["generic", "claude", "cursor", "copilot"] : [options.agent];
@@ -244,6 +408,339 @@ export function initAgentFiles(options) {
     }
     return written;
 }
+function validateAssetReadiness(profile, options) {
+    const projectDir = resolve(options.projectDir ?? process.cwd());
+    const sourceManifest = readAssetManifest(projectDir);
+    const manifest = filterAssetManifest(sourceManifest, options.assetIds);
+    const manifestPath = resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST);
+    const evidencePath = options.output ? resolve(projectDir, options.output) : undefined;
+    const validation = validateAssets({
+        projectDir,
+        noPlaceholders: options.noPlaceholders,
+        requireLicense: options.requireLicense,
+        provenanceFile: options.provenanceFile,
+        assetIds: options.assetIds
+    });
+    const externalProvenance = readExternalProvenance(projectDir, options.provenanceFile);
+    const failures = [...validation.failures];
+    const warnings = [...validation.warnings];
+    const modelAssets = manifest.assets.filter((asset) => asset.type === "model");
+    const animatedModels = modelAssets.filter((asset) => asset.animations.length > 0);
+    const animationClips = manifest.assets.reduce((total, asset) => total + asset.animations.length, 0);
+    const humanoidModels = modelAssets.filter((asset) => asset.humanoid?.humanoid).length;
+    const artifacts = createReadinessArtifacts(projectDir, manifest, evidencePath);
+    const assets = manifest.assets.map((asset) => {
+        const provenance = resolveAssetProvenance(asset, externalProvenance);
+        const placeholderFree = !isPlaceholderAsset(asset, provenance);
+        const licenseVerified = hasUsableLicenseEvidence(provenance);
+        const assetWarnings = [...asset.warnings];
+        const readinessIssues = createAssetReadinessIssues(profile, asset);
+        if (asset.type === "model" && !asset.bounds)
+            assetWarnings.push("Missing bounds; camera framing, collision proxies, and thumbnail composition will be weaker.");
+        if (asset.type === "model" && asset.materials.length === 0)
+            assetWarnings.push("No material names detected; authored visual diagnostics will be limited.");
+        if (asset.type === "model" && asset.sizeBytes > 50 * 1024 * 1024)
+            assetWarnings.push("Large model over 50MB; consider mesh/texture optimization before browser deployment.");
+        if (asset.type === "model" && asset.animations.length > 0 && asset.humanoid?.status === "unknown")
+            assetWarnings.push("Animated model has unknown humanoid status; inspect with --humanoid before using it as an acted character.");
+        assetWarnings.push(...readinessIssues.warnings);
+        failures.push(...readinessIssues.failures);
+        warnings.push(...readinessIssues.warnings);
+        const gameReady = asset.type === "model" && Boolean(asset.bounds) && asset.materials.length > 0 && asset.sizeBytes <= 50 * 1024 * 1024 && readinessIssues.failures.length === 0;
+        const cartoonReady = asset.type === "model"
+            ? Boolean(asset.bounds) && (asset.animations.length > 0 || /prop|set|stage|background|environment/i.test(asset.id))
+            : asset.type === "audio" || asset.type === "texture";
+        const artifactPaths = artifacts.assetFiles.find((entry) => entry.id === asset.id) ?? createReadinessAssetArtifacts(projectDir, manifest, asset);
+        return {
+            id: asset.id,
+            type: asset.type,
+            format: asset.format,
+            source: asset.source,
+            outputPath: asset.outputPath,
+            url: asset.url,
+            sizeBytes: asset.sizeBytes,
+            bounds: asset.bounds,
+            boundsMetadata: asset.boundsMetadata,
+            animations: asset.animations,
+            animation: createReadinessAnimationMetadata(asset.animations),
+            animationMetadata: asset.animationMetadata,
+            humanoid: asset.humanoid,
+            skeleton: asset.skeleton,
+            morphTargets: asset.morphTargets,
+            provenance,
+            placeholderFree,
+            licenseVerified,
+            materials: asset.materials,
+            materialMetadata: asset.materialMetadata,
+            textures: asset.textures,
+            orientation: asset.orientation,
+            nodeNames: asset.nodeNames,
+            artifactPaths,
+            gameReady,
+            cartoonReady,
+            warnings: assetWarnings
+        };
+    });
+    if (profile === "game") {
+        if (modelAssets.length === 0)
+            failures.push("Game readiness requires at least one typed model asset. Add a GLB/GLTF with aura3d assets add ./fighter.glb --name fighter.");
+        if (animatedModels.length === 0)
+            warnings.push("No animated model clips detected. Static scenes can ship, but playable character showcases should include idle/walk/attack/hurt clips.");
+        if (animatedModels.length > 0 && humanoidModels === 0)
+            warnings.push("No humanoid model metadata detected. Character-heavy game routes should confirm humanoid status with assets inspect --humanoid and typed asset metadata.");
+        for (const asset of assets) {
+            if (asset.type !== "model")
+                continue;
+            if (!asset.gameReady)
+                warnings.push(`${asset.id}: not game-ready yet; expected bounds, named materials, and browser-sized payload.`);
+        }
+    }
+    else {
+        if (modelAssets.length === 0)
+            failures.push("Cartoon readiness requires at least one typed model/set/prop GLB or GLTF.");
+        if (animatedModels.length === 0)
+            warnings.push("No animated character clips detected. Prompt-to-episode output can use transform animation, but character acting needs skeletal or pose clips.");
+        if (animatedModels.length > 0 && humanoidModels === 0)
+            warnings.push("No humanoid model metadata detected. Acting-heavy cartoon routes should confirm character rigs with assets inspect --humanoid.");
+        const audioAssets = manifest.assets.filter((asset) => asset.type === "audio");
+        if (audioAssets.length === 0)
+            warnings.push("No audio assets detected. AuraVoice bridge can still reference external narration manifests, but local episode proof is stronger with audio registered.");
+    }
+    const ok = failures.length === 0;
+    const baseMessage = ok
+        ? `${profile === "game" ? "Game" : "Cartoon"} asset readiness report completed.`
+        : failures;
+    const messages = [
+        ...(Array.isArray(baseMessage) ? baseMessage : [baseMessage]),
+        ...(evidencePath ? [`Wrote asset readiness evidence: ${normalizeRelativePath(relative(projectDir, evidencePath))}`] : [])
+    ];
+    const report = {
+        schema: "aura3d.asset-readiness/1.0",
+        profile,
+        ok,
+        status: ok ? "passed" : "failed",
+        validator: createReadinessValidatorEvidence(profile),
+        checkedAt: new Date().toISOString(),
+        manifestPath,
+        artifacts,
+        contracts: createReadinessValidationContracts(profile),
+        summary: {
+            totalAssets: manifest.assets.length,
+            modelAssets: modelAssets.length,
+            animatedModels: animatedModels.length,
+            textureAssets: manifest.assets.filter((asset) => asset.type === "texture").length,
+            audioAssets: manifest.assets.filter((asset) => asset.type === "audio").length,
+            environmentAssets: manifest.assets.filter((asset) => asset.type === "environment").length,
+            animationClips,
+            humanoidModels
+        },
+        assets,
+        failures,
+        warnings,
+        messages
+    };
+    if (evidencePath) {
+        mkdirSync(dirname(evidencePath), { recursive: true });
+        writeFileSync(evidencePath, `${JSON.stringify(report, null, 2)}\n`);
+    }
+    return report;
+}
+function filterAssetManifest(manifest, assetIds) {
+    const normalized = normalizeAssetIdFilter(assetIds);
+    if (normalized.length === 0)
+        return manifest;
+    const allowed = new Set(normalized);
+    return {
+        ...manifest,
+        assets: manifest.assets.filter((asset) => allowed.has(asset.id))
+    };
+}
+function findMissingAssetIds(manifest, assetIds) {
+    const normalized = normalizeAssetIdFilter(assetIds);
+    if (normalized.length === 0)
+        return [];
+    const existing = new Set(manifest.assets.map((asset) => asset.id));
+    return normalized.filter((id) => !existing.has(id));
+}
+function normalizeAssetIdFilter(assetIds) {
+    return [...new Set((assetIds ?? []).map((id) => id.trim()).filter(Boolean))];
+}
+function createReadinessValidatorEvidence(profile) {
+    return profile === "game"
+        ? {
+            id: "aura-clash-game-assets",
+            command: "assets validate-game",
+            label: "AuraClash game asset validator"
+        }
+        : {
+            id: "aura-voice-cartoon-assets",
+            command: "assets validate-cartoon",
+            label: "AuraVoice cartoon asset validator"
+        };
+}
+function createReadinessValidationContracts(profile) {
+    if (profile === "game") {
+        return [
+            {
+                id: "quaternius-game-ready-fighter-validation-contract",
+                label: "Quaternius-derived game-ready fighter validation contract",
+                profile: "game",
+                sourceFamily: "Quaternius",
+                intendedUse: "fighter",
+                sourceOnly: true,
+                requiredChecks: [
+                    "typed Aura model asset entry generated by assets add",
+                    "Quaternius provenance or source-family metadata",
+                    "GLB/GLTF model with browser-sized payload",
+                    "bounds with grounded pivot and fighter-scale dimensions",
+                    "forward-facing +z or z orientation before runtime mirroring",
+                    "humanoid skeleton metadata suitable for retarget diagnostics",
+                    "readable visible materials and texture budget",
+                    "thumbnail or first-frame artifact path",
+                    "non-empty named fighting animation clips",
+                    "no floating hair-only assembly without a body/head anchor"
+                ],
+                requiredAnimationClips: ["idle", "walk", "lightPunch"],
+                evidenceBoundary: "This CLI contract is source-only. It does not prove a Quaternius fighter passed validation until assets validate-game output and retained runtime/browser evidence are archived."
+            }
+        ];
+    }
+    return [
+        {
+            id: "auravoice-cartoon-character-asset-validation-contract",
+            label: "AuraVoice cartoon asset validation contract",
+            profile: "cartoon",
+            sourceFamily: "AuraVoice",
+            intendedUse: "cartoon-character",
+            sourceOnly: true,
+            requiredChecks: [
+                "typed Aura model, texture, audio, or environment asset entry",
+                "bounds for model/set composition",
+                "animation or transform-ready character metadata",
+                "audio or external AuraVoice manifest references for stronger episode proof"
+            ],
+            evidenceBoundary: "This CLI contract is source-only. It does not prove cartoon route readiness until validate-cartoon output, rendered frames, timing proof, and AuraVoice evidence are archived."
+        }
+    ];
+}
+function createReadinessArtifacts(projectDir, manifest, evidencePath) {
+    const artifacts = {
+        manifestPath: resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST),
+        typedAssetsPath: resolve(projectDir, manifest.typegen),
+        outputDir: resolve(projectDir, manifest.outputDir),
+        assetBasePath: manifest.assetBasePath,
+        assetFiles: manifest.assets.map((asset) => createReadinessAssetArtifacts(projectDir, manifest, asset))
+    };
+    if (evidencePath)
+        artifacts.evidencePath = evidencePath;
+    return artifacts;
+}
+function createReadinessAssetArtifacts(projectDir, manifest, asset) {
+    const artifact = {
+        id: asset.id,
+        sourcePath: resolve(projectDir, asset.source),
+        outputPath: resolve(projectDir, asset.outputPath),
+        publicUrl: asset.url,
+        dependencyPaths: (asset.dependencies ?? []).map((dependency) => resolve(dirname(resolve(projectDir, asset.outputPath)), dependency))
+    };
+    if (asset.thumbnailUrl) {
+        artifact.thumbnailUrl = asset.thumbnailUrl;
+        const thumbnailPath = resolvePublicArtifactPath(projectDir, manifest, asset.thumbnailUrl);
+        if (thumbnailPath)
+            artifact.thumbnailPath = thumbnailPath;
+    }
+    return artifact;
+}
+function createReadinessAnimationMetadata(animations) {
+    return {
+        clipCount: animations.length,
+        clips: animations.map((name, index) => ({ index, name }))
+    };
+}
+function createAssetReadinessIssues(profile, asset) {
+    if (asset.type !== "model")
+        return { failures: [], warnings: [] };
+    const failures = [];
+    const warnings = [];
+    const prefix = `${asset.id}:`;
+    const characterLike = isCharacterLikeAsset(asset);
+    if (profile === "game" && characterLike) {
+        const missing = missingRequiredGameClips(asset.animations);
+        if (missing.length > 0) {
+            failures.push(`${prefix} missing required game animation clip${missing.length === 1 ? "" : "s"}: ${missing.join(", ")}.`);
+        }
+    }
+    const emptyClips = (asset.animationMetadata?.clips ?? []).filter((clip) => clip.channelCount === 0 || clip.samplerCount === 0);
+    for (const clip of emptyClips) {
+        failures.push(`${prefix} animation clip "${clip.name}" is empty; expected at least one channel and sampler.`);
+    }
+    const bounds = asset.boundsMetadata;
+    if (bounds && bounds.maxDimension > 50) {
+        failures.push(`${prefix} oversized bounds detected; largest dimension is ${bounds.maxDimension}m, expected at most 50m for browser game assets.`);
+    }
+    else if (bounds && characterLike && bounds.maxDimension > 4) {
+        warnings.push(`${prefix} character-sized model is unusually large (${bounds.maxDimension}m); confirm scale before using it in gameplay.`);
+    }
+    if (bounds && characterLike && !bounds.grounded) {
+        warnings.push(`${prefix} bounds are not grounded at the pivot; min.y is ${bounds.min[1]}m.`);
+    }
+    const orientation = asset.orientation;
+    if (profile === "game" && characterLike && orientation?.forwardAxis && !["+z", "z"].includes(orientation.forwardAxis.toLowerCase())) {
+        failures.push(`${prefix} wrong facing direction "${orientation.forwardAxis}"; fighting-game characters are expected to face +z before runtime mirroring.`);
+    }
+    const invisibleMaterials = (asset.materialMetadata ?? []).filter((material) => !material.visible || !material.readable);
+    for (const material of invisibleMaterials) {
+        failures.push(`${prefix} invisible or unreadable material "${material.name}" detected${material.reasons.length ? ` (${material.reasons.join("; ")})` : ""}.`);
+    }
+    if (profile === "game" && hasFloatingHairRisk(asset)) {
+        failures.push(`${prefix} floating hair risk detected; hair-only geometry must be assembled onto a body/head with assets assemble-character before game validation.`);
+    }
+    return { failures, warnings };
+}
+function isCharacterLikeAsset(asset) {
+    if (asset.humanoid?.humanoid)
+        return true;
+    return /fighter|player|opponent|enemy|hero|character|avatar|humanoid|npc|body|mara/i.test(asset.id);
+}
+function missingRequiredGameClips(animations) {
+    const normalized = animations.map((name) => name.toLowerCase().replace(/[^a-z0-9]/g, ""));
+    const hasNamed = (patterns) => normalized.some((name) => patterns.some((pattern) => pattern.test(name)));
+    const missing = [];
+    if (!hasNamed([/idle/, /stand/]))
+        missing.push("idle");
+    if (!hasNamed([/walk/, /locomotion/, /move/]))
+        missing.push("walk");
+    if (!hasNamed([/lightpunch/, /lightattack/, /light/, /jab/, /punch/, /attack/]))
+        missing.push("lightPunch");
+    return missing;
+}
+function hasFloatingHairRisk(asset) {
+    const names = [asset.id, ...(asset.nodeNames ?? [])].join(" ").toLowerCase();
+    if (!names.includes("hair"))
+        return false;
+    const hasBodyAnchor = /body|torso|spine|chest|head|neck|skull|face|hips|pelvis/.test(names);
+    return !hasBodyAnchor;
+}
+function resolvePublicArtifactPath(projectDir, manifest, url) {
+    if (/^https?:\/\//i.test(url))
+        return undefined;
+    if (url.startsWith(manifest.assetBasePath)) {
+        return resolve(projectDir, manifest.outputDir, url.slice(manifest.assetBasePath.length));
+    }
+    return resolve(projectDir, url.replace(/^\//, "public/"));
+}
+function defaultAttachPoint(slot) {
+    const normalized = slot.toLowerCase();
+    if (normalized.includes("hair") || normalized.includes("hat") || normalized.includes("face"))
+        return "head";
+    if (normalized.includes("hand") || normalized.includes("weapon") || normalized.includes("prop"))
+        return "rightHand";
+    if (normalized.includes("shoe") || normalized.includes("boot"))
+        return "feet";
+    if (normalized.includes("cape") || normalized.includes("back"))
+        return "spine";
+    return "root";
+}
 export function readAssetManifest(projectDir) {
     const manifestPath = resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST);
     if (!existsSync(manifestPath)) {
@@ -270,8 +767,15 @@ function inspectAssetFile(path, format) {
         return inspectGlb(readFileSync(path), dirname(path));
     return {
         materials: [],
+        materialMetadata: [],
         animations: [],
+        animation: emptyAnimationInspection(),
+        humanoid: unknownHumanoidInspection("Humanoid detection is only available for GLB/glTF model assets."),
+        skeleton: emptySkeletonInspection("Skeleton detection is only available for GLB/glTF model assets."),
+        morphTargets: emptyMorphTargetInspection("Morph target detection is only available for GLB/glTF model assets."),
         textures: [],
+        orientation: unknownOrientationInspection(),
+        nodeNames: [],
         dependencies: [],
         bounds: undefined
     };
@@ -300,18 +804,226 @@ function inspectGltf(json, baseDir) {
             throw new Error(`Aura3D assets add failed: referenced asset file missing: ${missing.join(", ")}. Suggested fix: keep external .bin and texture files beside the .gltf or export as .glb.`);
         }
     }
+    const boundsMetadata = extractBoundsDetails(json);
     return {
-        bounds: extractBounds(json),
+        bounds: boundsMetadata?.size,
+        boundsMetadata,
         materials: (json.materials ?? []).map((material, index) => material.name ?? `material-${index}`),
+        materialMetadata: inspectGltfMaterials(json),
         animations: (json.animations ?? []).map((animation, index) => animation.name ?? `clip-${index}`),
+        animation: inspectGltfAnimations(json),
+        humanoid: inspectGltfHumanoid(json),
+        skeleton: inspectGltfSkeleton(json),
+        morphTargets: inspectGltfMorphTargets(json),
+        provenance: inspectGltfProvenance(json),
         textures: (json.images ?? []).map((image, index) => image.uri ?? image.name ?? `image-${index}`),
+        orientation: inspectGltfOrientation(json),
+        nodeNames: (json.nodes ?? []).map((node, index) => node.name ?? `node-${index}`),
         dependencies
     };
 }
+function emptyAnimationInspection() {
+    return {
+        clipCount: 0,
+        clips: [],
+        messages: ["No embedded animation clips detected."]
+    };
+}
+function inspectGltfAnimations(json) {
+    const clips = (json.animations ?? []).map((animation, index) => {
+        const channels = animation.channels ?? [];
+        const targetPaths = uniqueStrings(channels.map((channel) => channel.target?.path).filter(isString));
+        const targetNodes = uniqueStrings(channels.map((channel) => {
+            const nodeIndex = channel.target?.node;
+            return typeof nodeIndex === "number" ? json.nodes?.[nodeIndex]?.name ?? `node-${nodeIndex}` : undefined;
+        }).filter(isString));
+        return {
+            index,
+            name: animation.name ?? `clip-${index}`,
+            channelCount: channels.length,
+            samplerCount: animation.samplers?.length ?? 0,
+            targetPaths,
+            targetNodes
+        };
+    });
+    return {
+        clipCount: clips.length,
+        clips,
+        messages: clips.length === 0
+            ? ["No embedded animation clips detected."]
+            : [`Detected ${clips.length} embedded animation clip${clips.length === 1 ? "" : "s"}.`]
+    };
+}
+function inspectGltfHumanoid(json) {
+    const skinCount = json.skins?.length ?? 0;
+    const jointIndexes = uniqueNumbers((json.skins ?? []).flatMap((skin) => skin.joints ?? []));
+    const jointNames = uniqueStrings(jointIndexes.map((index) => json.nodes?.[index]?.name ?? `joint-${index}`));
+    const nodeNames = uniqueStrings((json.nodes ?? []).map((node, index) => node.name ?? `node-${index}`));
+    const candidates = jointNames.length > 0 ? jointNames : nodeNames;
+    const requiredBones = ["hips", "spine", "head", "leftArm", "rightArm", "leftLeg", "rightLeg"];
+    const matchedBones = requiredBones.filter((bone) => candidates.some((name) => matchesHumanoidBone(name, bone)));
+    const missingBones = requiredBones.filter((bone) => !matchedBones.includes(bone));
+    const hasSkin = jointIndexes.length > 0;
+    const hasTorso = matchedBones.includes("hips") && matchedBones.includes("spine") && matchedBones.includes("head");
+    const hasArms = matchedBones.includes("leftArm") && matchedBones.includes("rightArm");
+    const hasLegs = matchedBones.includes("leftLeg") && matchedBones.includes("rightLeg");
+    const humanoid = (hasSkin && hasTorso && hasArms && hasLegs) || (!hasSkin && hasTorso && matchedBones.length >= 5);
+    const status = humanoid
+        ? "humanoid"
+        : hasSkin || matchedBones.length > 0
+            ? "unknown"
+            : "non-humanoid";
+    const confidence = humanoid && hasSkin
+        ? "high"
+        : humanoid || (hasSkin && matchedBones.length >= 5)
+            ? "medium"
+            : "low";
+    return {
+        humanoid,
+        status,
+        confidence,
+        skinCount,
+        jointCount: jointIndexes.length,
+        matchedBones,
+        missingBones,
+        messages: humanoid
+            ? [`Humanoid signals detected from ${hasSkin ? "skinned joints" : "node names"}.`]
+            : status === "unknown"
+                ? [`Humanoid status is unknown; missing bone groups: ${missingBones.join(", ")}.`]
+                : ["No humanoid skeleton signals detected."]
+    };
+}
+function inspectGltfSkeleton(json) {
+    const skins = (json.skins ?? []).map((skin, index) => {
+        const joints = (skin.joints ?? []).map((jointIndex) => json.nodes?.[jointIndex]?.name ?? `joint-${jointIndex}`);
+        const skeletonIndex = skin.skeleton;
+        return {
+            index,
+            name: skin.name ?? `skin-${index}`,
+            jointCount: joints.length,
+            joints,
+            ...(typeof skeletonIndex === "number" ? { skeleton: json.nodes?.[skeletonIndex]?.name ?? `node-${skeletonIndex}` } : {})
+        };
+    });
+    const jointCount = uniqueStrings(skins.flatMap((skin) => skin.joints)).length;
+    return {
+        skinCount: skins.length,
+        jointCount,
+        skins,
+        messages: skins.length === 0
+            ? ["No skin/skeleton metadata detected."]
+            : [`Detected ${skins.length} skin${skins.length === 1 ? "" : "s"} with ${jointCount} unique joint${jointCount === 1 ? "" : "s"}.`]
+    };
+}
+function emptySkeletonInspection(message) {
+    return {
+        skinCount: 0,
+        jointCount: 0,
+        skins: [],
+        messages: [message]
+    };
+}
+function inspectGltfMorphTargets(json) {
+    const meshes = (json.meshes ?? []).map((mesh, index) => {
+        const meshExtras = objectValue(mesh.extras);
+        const namedTargets = stringArrayValue(meshExtras?.targetNames ?? meshExtras?.morphTargetNames);
+        const targetCount = Math.max(namedTargets.length, mesh.weights?.length ?? 0, ...(mesh.primitives ?? []).map((primitive) => primitive.targets?.length ?? 0));
+        if (targetCount === 0)
+            return undefined;
+        const targetNames = targetCount > 0
+            ? Array.from({ length: targetCount }, (_, targetIndex) => namedTargets[targetIndex] ?? `target-${targetIndex}`)
+            : [];
+        return {
+            index,
+            name: mesh.name ?? `mesh-${index}`,
+            targetNames
+        };
+    }).filter((mesh) => Boolean(mesh));
+    const targetNames = uniqueStrings(meshes.flatMap((mesh) => mesh.targetNames));
+    return {
+        targetCount: targetNames.length,
+        targetNames,
+        meshes,
+        messages: targetNames.length === 0
+            ? ["No morph target metadata detected."]
+            : [`Detected ${targetNames.length} morph target${targetNames.length === 1 ? "" : "s"}.`]
+    };
+}
+function emptyMorphTargetInspection(message) {
+    return {
+        targetCount: 0,
+        targetNames: [],
+        meshes: [],
+        messages: [message]
+    };
+}
+function inspectGltfProvenance(json) {
+    const assetExtras = objectValue(json.asset?.extras);
+    const auraExtras = objectValue(assetExtras?.aura3d) ?? assetExtras;
+    const provenance = objectValue(auraExtras?.provenance ?? auraExtras?.license ?? auraExtras?.source);
+    const sourceUrl = stringValue(provenance?.sourceUrl ?? provenance?.url ?? auraExtras?.sourceUrl);
+    const license = stringValue(provenance?.license ?? provenance?.spdx ?? auraExtras?.license);
+    const author = stringValue(provenance?.author ?? provenance?.creator ?? auraExtras?.author);
+    const sourceFamily = stringValue(provenance?.sourceFamily ?? provenance?.source ?? auraExtras?.sourceFamily);
+    const attribution = stringValue(provenance?.attribution ?? auraExtras?.attribution);
+    const evidence = stringArrayValue(provenance?.evidence ?? auraExtras?.evidence);
+    if (!sourceUrl && !license && !author && !sourceFamily && !attribution && evidence.length === 0)
+        return undefined;
+    return {
+        ...(sourceUrl ? { sourceUrl } : {}),
+        ...(license ? { license } : {}),
+        ...(author ? { author } : {}),
+        ...(sourceFamily ? { sourceFamily } : {}),
+        ...(attribution ? { attribution } : {}),
+        ...(evidence.length > 0 ? { evidence } : {})
+    };
+}
+function unknownHumanoidInspection(message) {
+    return {
+        humanoid: false,
+        status: "unknown",
+        confidence: "low",
+        skinCount: 0,
+        jointCount: 0,
+        matchedBones: [],
+        missingBones: ["hips", "spine", "head", "leftArm", "rightArm", "leftLeg", "rightLeg"],
+        messages: [message]
+    };
+}
+function matchesHumanoidBone(name, bone) {
+    const raw = name.toLowerCase();
+    const compact = raw.replace(/[^a-z0-9]/g, "");
+    const left = compact.includes("left") || /(^|[^a-z0-9])l([^a-z0-9]|$)/.test(raw) || /[^a-z0-9]l$/.test(raw);
+    const right = compact.includes("right") || /(^|[^a-z0-9])r([^a-z0-9]|$)/.test(raw) || /[^a-z0-9]r$/.test(raw);
+    const arm = compact.includes("arm") || compact.includes("forearm") || compact.includes("shoulder") || compact.includes("hand");
+    const leg = compact.includes("leg") || compact.includes("thigh") || compact.includes("foot") || compact.includes("toe");
+    if (bone === "hips")
+        return compact.includes("hip") || compact.includes("pelvis");
+    if (bone === "spine")
+        return compact.includes("spine") || compact.includes("chest") || compact.includes("torso");
+    if (bone === "head")
+        return compact.includes("head") || compact.includes("neck");
+    if (bone === "leftArm")
+        return left && arm;
+    if (bone === "rightArm")
+        return right && arm;
+    if (bone === "leftLeg")
+        return left && leg;
+    return right && leg;
+}
 function isExternalUri(uri) {
     return typeof uri === "string" && uri.length > 0 && !uri.startsWith("data:");
 }
-function extractBounds(json) {
+function isString(value) {
+    return typeof value === "string";
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function uniqueNumbers(values) {
+    return [...new Set(values)];
+}
+function extractBoundsDetails(json) {
     let min;
     let max;
     for (const accessor of json.accessors ?? []) {
@@ -320,7 +1032,89 @@ function extractBounds(json) {
         min = min ? [Math.min(min[0], accessor.min[0]), Math.min(min[1], accessor.min[1]), Math.min(min[2], accessor.min[2])] : [accessor.min[0], accessor.min[1], accessor.min[2]];
         max = max ? [Math.max(max[0], accessor.max[0]), Math.max(max[1], accessor.max[1]), Math.max(max[2], accessor.max[2])] : [accessor.max[0], accessor.max[1], accessor.max[2]];
     }
-    return min && max ? [round(max[0] - min[0]), round(max[1] - min[1]), round(max[2] - min[2])] : undefined;
+    if (!min || !max)
+        return undefined;
+    const size = [round(max[0] - min[0]), round(max[1] - min[1]), round(max[2] - min[2])];
+    const center = [round((min[0] + max[0]) / 2), round((min[1] + max[1]) / 2), round((min[2] + max[2]) / 2)];
+    const roundedMin = [round(min[0]), round(min[1]), round(min[2])];
+    const roundedMax = [round(max[0]), round(max[1]), round(max[2])];
+    return {
+        min: roundedMin,
+        max: roundedMax,
+        size,
+        center,
+        maxDimension: Math.max(...size),
+        grounded: Math.abs(roundedMin[1]) <= 0.08
+    };
+}
+function inspectGltfMaterials(json) {
+    return (json.materials ?? []).map((material, index) => {
+        const name = material.name ?? `material-${index}`;
+        const extras = objectValue(material.extras);
+        const explicitVisible = booleanValue(extras?.visible);
+        const explicitReadable = booleanValue(extras?.readable);
+        const opacity = round(numberValue(material.pbrMetallicRoughness?.baseColorFactor?.[3]) ?? 1);
+        const alphaMode = material.alphaMode;
+        const alphaCutoff = numberValue(material.alphaCutoff);
+        const reasons = [];
+        if (opacity <= 0)
+            reasons.push("baseColorFactor alpha is 0");
+        if (alphaMode === "MASK" && (alphaCutoff ?? 0.5) >= 1)
+            reasons.push("alpha mask cutoff hides fully transparent surfaces");
+        if (explicitVisible === false)
+            reasons.push("material extras mark visible=false");
+        if (explicitReadable === false)
+            reasons.push("material extras mark readable=false");
+        const visible = explicitVisible ?? (opacity > 0 && !(alphaMode === "MASK" && (alphaCutoff ?? 0.5) >= 1));
+        const readable = explicitReadable ?? visible;
+        return {
+            name,
+            visible,
+            readable,
+            opacity,
+            ...(alphaMode ? { alphaMode } : {}),
+            reasons
+        };
+    });
+}
+function inspectGltfOrientation(json) {
+    const assetExtras = objectValue(json.asset?.extras);
+    const auraExtras = objectValue(assetExtras?.aura3d) ?? assetExtras;
+    const orientation = objectValue(auraExtras?.orientation) ?? auraExtras;
+    const forwardAxis = stringValue(orientation?.forwardAxis ?? orientation?.forward ?? orientation?.facing);
+    const upAxis = stringValue(orientation?.upAxis ?? orientation?.up);
+    if (!forwardAxis && !upAxis)
+        return unknownOrientationInspection();
+    return {
+        source: "gltf-extras",
+        ...(forwardAxis ? { forwardAxis } : {}),
+        ...(upAxis ? { upAxis } : {}),
+        messages: [`Orientation metadata detected${forwardAxis ? ` with forwardAxis=${forwardAxis}` : ""}${upAxis ? ` and upAxis=${upAxis}` : ""}.`]
+    };
+}
+function unknownOrientationInspection() {
+    return {
+        source: "unknown",
+        messages: ["No orientation metadata detected; facing direction cannot be proven."]
+    };
+}
+function objectValue(value) {
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function stringArrayValue(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => stringValue(entry)).filter((entry) => Boolean(entry));
+}
+function booleanValue(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function numberValue(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
 }
 function createAssetWarnings(path, inspection) {
     const warnings = [];
@@ -331,8 +1125,96 @@ function createAssetWarnings(path, inspection) {
         warnings.push("bounds could not be extracted");
     if (inspection.textures.length === 0 && ["glb", "gltf"].includes(extname(path).slice(1).toLowerCase()))
         warnings.push("no texture references detected");
+    if (inspection.orientation.source === "unknown" && ["glb", "gltf"].includes(extname(path).slice(1).toLowerCase()))
+        warnings.push("orientation metadata missing; facing direction cannot be validated until GLTF extras declare aura3d.orientation.forwardAxis");
+    if (inspection.materialMetadata.some((material) => !material.visible || !material.readable))
+        warnings.push("one or more materials are invisible or unreadable");
     return warnings;
 }
+function createAssetProvenance(projectDir, sourcePath, options, detected) {
+    return {
+        sourcePath: normalizeRelativePath(relative(projectDir, sourcePath)),
+        ...(options.sourceUrl ?? detected?.sourceUrl ? { sourceUrl: options.sourceUrl ?? detected?.sourceUrl } : {}),
+        ...(options.license ?? detected?.license ? { license: options.license ?? detected?.license } : {}),
+        ...(options.author ?? detected?.author ? { author: options.author ?? detected?.author } : {}),
+        ...(options.sourceFamily ?? detected?.sourceFamily ? { sourceFamily: options.sourceFamily ?? detected?.sourceFamily } : {}),
+        ...(options.attribution ?? detected?.attribution ? { attribution: options.attribution ?? detected?.attribution } : {}),
+        ...(detected?.evidence && detected.evidence.length > 0 ? { evidence: detected.evidence } : {}),
+        checkedAt: new Date().toISOString()
+    };
+}
+function readExternalProvenance(projectDir, provenanceFile) {
+    if (!provenanceFile)
+        return new Map();
+    const path = resolve(projectDir, provenanceFile);
+    if (!existsSync(path))
+        return new Map();
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const root = objectValue(parsed);
+    if (!root)
+        return new Map();
+    const checkedAt = stringValue(root.updatedAt ?? root.verifiedAt ?? root.checkedAt) ?? new Date().toISOString();
+    const records = [
+        ...arrayObjectValue(root.launchGlbs),
+        ...arrayObjectValue(root.assets),
+        ...arrayObjectValue(root.assetEvidence)
+    ];
+    const byId = new Map();
+    for (const record of records) {
+        const typedAsset = stringValue(record.typedAsset);
+        const id = stringValue(record.assetKey ?? record.id) ?? typedAsset?.replace(/^assets\./, "");
+        if (!id)
+            continue;
+        const nestedProvenance = objectValue(record.provenance);
+        const sourcePath = stringValue(record.sourcePath ?? record.source ?? nestedProvenance?.builderOutput) ?? id;
+        const license = stringValue(record.license ?? record.licenseNote ?? nestedProvenance?.license);
+        const sourceUrl = stringValue(record.sourceUrl ?? record.publicUrl ?? record.officialPage ?? nestedProvenance?.sourceUrl);
+        const sourceFamily = stringValue(record.sourceFamily ?? nestedProvenance?.sourceFamily ?? nestedProvenance?.sourcePack);
+        const author = stringValue(record.author ?? nestedProvenance?.author);
+        const attribution = stringValue(record.attribution ?? record.credit ?? nestedProvenance?.attribution);
+        const evidence = [
+            ...stringArrayValue(record.evidence),
+            ...stringArrayValue(record.intendedRouteUsage),
+            ...stringArrayValue(nestedProvenance?.evidence)
+        ];
+        byId.set(id, {
+            sourcePath,
+            ...(sourceUrl ? { sourceUrl } : {}),
+            ...(license ? { license } : {}),
+            ...(author ? { author } : {}),
+            ...(sourceFamily ? { sourceFamily } : {}),
+            ...(attribution ? { attribution } : {}),
+            ...(evidence.length > 0 ? { evidence } : {}),
+            checkedAt
+        });
+    }
+    return byId;
+}
+function arrayObjectValue(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((entry) => objectValue(entry)).filter((entry) => Boolean(entry));
+}
+function resolveAssetProvenance(asset, externalProvenance) {
+    return asset.provenance ?? externalProvenance.get(asset.id);
+}
+function hasUsableLicenseEvidence(provenance) {
+    const license = provenance?.license?.trim();
+    if (!license)
+        return false;
+    return !/(unverified|unknown|candidate|needs[-\s]?confirmation|todo|placeholder)/i.test(license);
+}
+function isPlaceholderAsset(asset, provenance) {
+    const value = [
+        asset.id,
+        asset.source,
+        asset.outputPath,
+        asset.url,
+        provenance?.sourcePath,
+        provenance?.sourceUrl
+    ].filter(Boolean).join(" ");
+    return /(^|[-_./\s])(placeholder|dummy|mock|todo|replace-me|sample-placeholder)([-_./\s]|$)/i.test(value);
+}
 function copyAssetDependencies(projectDir, sourcePath, outputDir, dependencies) {
     const sourceDir = dirname(sourcePath);
     for (const dependency of dependencies) {