@aura3d/engine 1.0.10 → 1.3.0

package/dist/aura3d-cli/index.js

@@ -1,7 +1,8 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { dirname, extname, join, relative, resolve } from "node:path";
-export { cartoonCliAssetProfiles, getCartoonAssetProfileDefinition } from "./cartoon-asset-profiles.js";
+export { animationCliAssetProfiles, getAnimationAssetProfileDefinition } from "./animation-asset-profiles.js";
+export { validateAnimationAssets, parseAnimationClipMap, DEFAULT_ANIMATION_ACTIONS } from "./animation-asset-validator.js";
 export const DEFAULT_AURA_ASSET_MANIFEST = "aura.assets.json";
 export const DEFAULT_AURA_ASSET_OUTPUT_DIR = "public/aura-assets";
 export const DEFAULT_AURA_ASSET_PUBLIC_PATH = "/aura-assets/";
@@ -14,6 +15,9 @@ export function addAsset(options) {
     }
     const manifestPath = resolve(projectDir, DEFAULT_AURA_ASSET_MANIFEST);
     const current = readAssetManifest(projectDir);
+    // Re-adding (e.g. resolve overwriting) must not silently drop hand-authored
+    // provenance the new add does not re-supply (license/attribution/author/etc.).
+    const existing = current.assets.find((asset) => asset.id === options.name);
     const outputDir = normalizeRelativePath(options.outputDir ?? current.outputDir ?? DEFAULT_AURA_ASSET_OUTPUT_DIR);
     const publicPath = normalizePublicPath(options.publicPath ?? current.assetBasePath ?? DEFAULT_AURA_ASSET_PUBLIC_PATH);
     const typegen = normalizeRelativePath(options.typegen ?? current.typegen ?? DEFAULT_AURA_ASSET_TYPEGEN);
@@ -47,7 +51,7 @@ export function addAsset(options) {
         humanoid: inspection.humanoid,
         skeleton: inspection.skeleton,
         morphTargets: inspection.morphTargets,
-        provenance: createAssetProvenance(projectDir, sourcePath, options, inspection.provenance),
+        provenance: createAssetProvenance(projectDir, sourcePath, options, mergeDetectedProvenance(existing?.provenance, inspection.provenance)),
         textures: inspection.textures,
         dependencies: inspection.dependencies,
         orientation: inspection.orientation,
@@ -305,8 +309,8 @@ export function checkDeploy(options = {}) {
 export function validateGameAssets(options = {}) {
     return validateAssetReadiness("game", options);
 }
-export function validateCartoonAssets(options = {}) {
-    return validateAssetReadiness("cartoon", options);
+export function validateAnimationStudioAssets(options = {}) {
+    return validateAssetReadiness("animation", options);
 }
 export function createCharacterAssemblyPlan(options) {
     const projectDir = resolve(options.projectDir ?? process.cwd());
@@ -468,7 +472,7 @@ function validateAssetReadiness(profile, options) {
         pushUnique(warnings, [...readinessIssues.warnings, ...profileIssues.warnings]);
         const gameReady = asset.type === "model" && Boolean(asset.bounds) && asset.materials.length > 0 && asset.sizeBytes <= 50 * 1024 * 1024 && readinessIssues.failures.length === 0 && profileIssues.failures.length === 0;
         const profileReady = profileTarget && gameReady;
-        const cartoonReady = asset.type === "model"
+        const animationReady = 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);
@@ -479,6 +483,7 @@ function validateAssetReadiness(profile, options) {
             source: asset.source,
             outputPath: asset.outputPath,
             url: asset.url,
+            hash: asset.hash,
             sizeBytes: asset.sizeBytes,
             bounds: asset.bounds,
             boundsMetadata: asset.boundsMetadata,
@@ -498,7 +503,7 @@ function validateAssetReadiness(profile, options) {
             nodeNames: asset.nodeNames,
             artifactPaths,
             gameReady,
-            cartoonReady,
+            animationReady,
             ...(gameProfile === "fighting-character" ? { profileTarget, profileReady, ...(profileSkippedReason ? { profileSkippedReason } : {}) } : {}),
             warnings: assetWarnings
         };
@@ -543,18 +548,25 @@ function validateAssetReadiness(profile, options) {
     }
     else {
         if (modelAssets.length === 0)
-            failures.push("Cartoon readiness requires at least one typed model/set/prop GLB or GLTF.");
+            failures.push("Animation 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.");
+            warnings.push("No humanoid model metadata detected. Acting-heavy animation 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 animationEpisode = profile === "animation"
+        ? createAnimationEpisodeReadinessReport(manifest, assets, options)
+        : undefined;
+    if (animationEpisode && options.episode) {
+        pushUnique(failures, animationEpisode.failures);
+        pushUnique(warnings, animationEpisode.warnings);
+    }
     const ok = failures.length === 0;
     const baseMessage = ok
-        ? `${profile === "game" ? "Game" : "Cartoon"} asset readiness report completed.`
+        ? `${profile === "game" ? "Game" : "Animation"} asset readiness report completed.`
         : failures;
     const messages = [
         ...(Array.isArray(baseMessage) ? baseMessage : [baseMessage]),
@@ -571,6 +583,7 @@ function validateAssetReadiness(profile, options) {
         manifestPath,
         artifacts,
         contracts: createReadinessValidationContracts(profile),
+        ...(animationEpisode ? { animationEpisode } : {}),
         summary: {
             totalAssets: manifest.assets.length,
             modelAssets: modelAssets.length,
@@ -580,6 +593,16 @@ function validateAssetReadiness(profile, options) {
             environmentAssets: manifest.assets.filter((asset) => asset.type === "environment").length,
             animationClips,
             humanoidModels,
+            ...(animationEpisode
+                ? {
+                    animationCharacters: animationEpisode.selectedCharacters.length,
+                    animationSets: animationEpisode.selectedSets.length,
+                    animationProps: animationEpisode.selectedProps.length,
+                    episodeReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.episodeReady).length,
+                    mouthReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.mouthReady).length,
+                    animationReadyCharacters: animationEpisode.readiness.filter((entry) => entry.role === "character" && entry.animationReady).length
+                }
+                : {}),
             ...(gameProfile === "fighting-character"
                 ? {
                     profileTargetAssets: profileTargetAssets.length,
@@ -641,9 +664,9 @@ function createReadinessValidatorEvidence(profile) {
             label: "AuraClash game asset validator"
         }
         : {
-            id: "aura-voice-cartoon-assets",
-            command: "assets validate-cartoon",
-            label: "AuraVoice cartoon asset validator"
+            id: "aura-voice-animation-assets",
+            command: "assets validate-animation",
+            label: "AuraVoice animation asset validator"
         };
 }
 function createReadinessValidationContracts(profile) {
@@ -675,11 +698,11 @@ function createReadinessValidationContracts(profile) {
     }
     return [
         {
-            id: "auravoice-cartoon-character-asset-validation-contract",
-            label: "AuraVoice cartoon asset validation contract",
-            profile: "cartoon",
+            id: "auravoice-animation-character-asset-validation-contract",
+            label: "AuraVoice animation asset validation contract",
+            profile: "animation",
             sourceFamily: "AuraVoice",
-            intendedUse: "cartoon-character",
+            intendedUse: "animation-character",
             sourceOnly: true,
             requiredChecks: [
                 "typed Aura model, texture, audio, or environment asset entry",
@@ -687,7 +710,7 @@ function createReadinessValidationContracts(profile) {
                 "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."
+            evidenceBoundary: "This CLI contract is source-only. It does not prove animation route readiness until validate-animation output, rendered frames, timing proof, and AuraVoice evidence are archived."
         }
     ];
 }
@@ -725,6 +748,198 @@ function createReadinessAnimationMetadata(animations) {
         clips: animations.map((name, index) => ({ index, name }))
     };
 }
+function createAnimationEpisodeReadinessReport(manifest, assets, options) {
+    const readiness = assets.map(createAnimationEpisodeAssetReadiness);
+    const characters = readiness.filter((entry) => entry.role === "character");
+    const sets = readiness.filter((entry) => entry.role === "set");
+    const props = readiness.filter((entry) => entry.role === "prop");
+    const audio = readiness.filter((entry) => entry.role === "audio");
+    const failures = [];
+    const warnings = [];
+    const distinctCharacterHashes = new Set(characters.map((entry) => entry.distinctHash).filter(Boolean));
+    const readyCharacters = characters.filter((entry) => entry.episodeReady);
+    const readySets = sets.filter((entry) => entry.episodeReady);
+    if (characters.length < 2) {
+        failures.push(`animation episode validation requires at least 2 typed animation character assets; found ${characters.length}${characters.length ? `: ${characters.map((entry) => entry.id).join(", ")}` : ""}.`);
+    }
+    if (characters.length >= 2 && distinctCharacterHashes.size < characters.length) {
+        failures.push("animation episode validation requires distinct character files/hashes; duplicated character assets cannot prove a two-character episode cast.");
+    }
+    if (readyCharacters.length < 2) {
+        failures.push(`animation episode validation found only ${readyCharacters.length} episode-ready character asset${readyCharacters.length === 1 ? "" : "s"}; required 2 with license, provenance, animation, and mouth readiness.`);
+    }
+    if (sets.length < 1) {
+        failures.push("animation episode validation requires at least 1 typed animation set/location asset.");
+    }
+    if (readySets.length < 1) {
+        failures.push("animation episode validation requires at least 1 episode-ready set with license, provenance, bounds, readable materials, and walkable scale.");
+    }
+    for (const entry of readiness) {
+        pushUnique(failures, entry.failures);
+        pushUnique(warnings, entry.warnings);
+    }
+    if (audio.length === 0) {
+        warnings.push("animation episode validation found no typed audio assets; publish-ready dialogue/audio proof will need registered dialogue, music, or SFX stems.");
+    }
+    const evidenceDirectory = options.output ? dirname(normalizeRelativePath(options.output)) : "artifacts/aura3d";
+    return {
+        enabled: Boolean(options.episode),
+        ok: failures.length === 0,
+        mode: "episode-ready",
+        requirements: {
+            minDistinctCharacters: 2,
+            minSets: 1,
+            requireLicense: true,
+            noPlaceholders: true,
+            requireAnimation: true,
+            requireMouthMotion: true,
+            requireSetScale: true
+        },
+        selectedCharacters: characters.map((entry) => entry.id),
+        selectedSets: sets.map((entry) => entry.id),
+        selectedProps: props.map((entry) => entry.id),
+        selectedAudio: audio.map((entry) => entry.id),
+        readiness,
+        assetProvenanceArtifact: normalizeRelativePath(join(evidenceDirectory, "asset-provenance.json")),
+        failures,
+        warnings
+    };
+}
+function createAnimationEpisodeAssetReadiness(asset) {
+    const role = inferAnimationEpisodeAssetRole(asset);
+    const failures = [];
+    const warnings = [];
+    const provenanceReady = Boolean(asset.provenance?.sourceUrl || asset.provenance?.sourceFamily || asset.provenance?.sourcePath);
+    const animationReady = role === "character" ? isAnimationCharacterAnimationReady(asset) : asset.animations.length > 0;
+    const mouthMode = role === "character" ? inferAnimationMouthMode(asset) : undefined;
+    const mouthReady = role === "character" ? mouthMode !== "missing-mouth-motion" : false;
+    const setReady = role === "set" ? isAnimationSetReady(asset) : undefined;
+    if (role === "character") {
+        if (asset.type !== "model")
+            failures.push(`${asset.id}: animation character must be a typed model asset, found ${asset.type}.`);
+        if (!asset.licenseVerified)
+            failures.push(`${asset.id}: animation character requires verified redistributable license evidence.`);
+        if (!provenanceReady)
+            failures.push(`${asset.id}: animation character requires source provenance for episode packaging.`);
+        if (!asset.placeholderFree)
+            failures.push(`${asset.id}: animation character is placeholder-tagged and cannot satisfy episode-ready validation.`);
+        if (!asset.boundsMetadata && !asset.bounds)
+            failures.push(`${asset.id}: animation character requires bounds metadata for framing and motion analysis.`);
+        if (!animationReady)
+            failures.push(`${asset.id}: animation character requires embedded animation clips or explicit segmented-rig metadata.`);
+        if (!mouthReady)
+            failures.push(`${asset.id}: animation character requires blendshape, mouth-card, viseme, talk, face, or primitive mouth fallback metadata.`);
+        if (asset.materials.length === 0)
+            failures.push(`${asset.id}: animation character requires at least one readable material.`);
+        if (asset.sizeBytes > 45 * 1024 * 1024)
+            failures.push(`${asset.id}: animation character payload is ${asset.sizeBytes} bytes; expected <= 47185920 for browser episode playback.`);
+        if (mouthMode === "amplitude-only")
+            warnings.push(`${asset.id}: mouth readiness is amplitude-only; add blendshape or mouth-card metadata for stronger lip-sync proof.`);
+    }
+    else if (role === "set") {
+        if (asset.type !== "model")
+            failures.push(`${asset.id}: animation set must be a typed model asset, found ${asset.type}.`);
+        if (!asset.licenseVerified)
+            failures.push(`${asset.id}: animation set requires verified redistributable license evidence.`);
+        if (!provenanceReady)
+            failures.push(`${asset.id}: animation set requires source provenance for episode packaging.`);
+        if (!asset.placeholderFree)
+            failures.push(`${asset.id}: animation set is placeholder-tagged and cannot satisfy episode-ready validation.`);
+        if (!setReady)
+            failures.push(`${asset.id}: animation set requires bounds, readable materials, and at least 1.5m walkable/framing scale.`);
+        if (asset.sizeBytes > 90 * 1024 * 1024)
+            failures.push(`${asset.id}: animation set payload is ${asset.sizeBytes} bytes; expected <= 94371840 for browser episode playback.`);
+    }
+    else if (role === "prop" || role === "environment") {
+        if (!asset.licenseVerified)
+            warnings.push(`${asset.id}: optional animation ${role} lacks verified license evidence; publish packages should include provenance for every visible asset.`);
+        if (!provenanceReady)
+            warnings.push(`${asset.id}: optional animation ${role} lacks source provenance.`);
+    }
+    return {
+        id: asset.id,
+        role,
+        episodeReady: role === "character"
+            ? failures.length === 0 && animationReady && mouthReady
+            : role === "set"
+                ? failures.length === 0 && Boolean(setReady)
+                : failures.length === 0,
+        distinctHash: role === "character" ? asset.hash : undefined,
+        licenseVerified: asset.licenseVerified,
+        provenanceReady,
+        placeholderFree: asset.placeholderFree,
+        animationReady,
+        mouthReady,
+        ...(mouthMode ? { mouthMode } : {}),
+        ...(typeof setReady === "boolean" ? { setReady } : {}),
+        warnings,
+        failures
+    };
+}
+function inferAnimationEpisodeAssetRole(asset) {
+    if (asset.type === "audio")
+        return "audio";
+    if (asset.type === "texture")
+        return "texture";
+    const text = animationAssetText(asset);
+    if (asset.type === "environment" || /\b(environment|skybox|backdrop|background|world|terrain|horizon)\b/i.test(text))
+        return "environment";
+    if (/\b(set|stage|room|garden|park|school|street|house|classroom|moon garden|walkable|floor|location)\b/i.test(text))
+        return "set";
+    if (/\b(character|humanoid|kid|child|hero|sidekick|villain|narrator|avatar|actor|miko|luma|robot|mascot|npc)\b/i.test(text))
+        return "character";
+    if (asset.humanoid?.humanoid || (asset.skeleton?.jointCount ?? 0) >= 6)
+        return "character";
+    if (asset.animations.length > 0 && asset.boundsMetadata && asset.boundsMetadata.size[1] >= 0.45 && asset.boundsMetadata.size[1] <= 4.5)
+        return "character";
+    if (asset.boundsMetadata && Math.max(...asset.boundsMetadata.size) >= 1.5 && asset.animations.length === 0)
+        return "set";
+    if (asset.type === "model")
+        return "prop";
+    return "unknown";
+}
+function isAnimationCharacterAnimationReady(asset) {
+    if (asset.animations.length > 0)
+        return true;
+    return /\b(segmented rig|segmented-rig|puppet rig|body parts|armature|skinned|skeleton)\b/i.test(animationAssetText(asset));
+}
+function inferAnimationMouthMode(asset) {
+    const morphNames = asset.morphTargets?.targetNames ?? [];
+    if (morphNames.some((name) => /\b(aa|oh|ee|mouth|lip|jaw|viseme|smile|frown|blink|expression)\b/i.test(name))) {
+        return "blendshape-lip-sync";
+    }
+    const text = animationAssetText(asset);
+    if (/\b(primitive mouth|mouth card|mouth-card|mouth sprite|face card|viseme card|2d mouth)\b/i.test(text)) {
+        return "primitive-mouth-card";
+    }
+    if (/\b(mouth|lip sync|lipsync|viseme|jaw|talk|speak|facial|face|expression|blendshape|blend shape|morph)\b/i.test(text)) {
+        return asset.morphTargets && asset.morphTargets.targetCount > 0 ? "blendshape-lip-sync" : "amplitude-only";
+    }
+    return "missing-mouth-motion";
+}
+function isAnimationSetReady(asset) {
+    const size = asset.boundsMetadata?.size ?? asset.bounds;
+    if (!size)
+        return false;
+    const largest = Math.max(...size);
+    return largest >= 1.5 && asset.materials.length > 0;
+}
+function animationAssetText(asset) {
+    return [
+        asset.id,
+        asset.source,
+        asset.url,
+        asset.outputPath,
+        asset.provenance?.sourceUrl ?? "",
+        asset.provenance?.sourceFamily ?? "",
+        asset.provenance?.author ?? "",
+        asset.provenance?.attribution ?? "",
+        ...(asset.provenance?.evidence ?? []),
+        ...(asset.nodeNames ?? []),
+        ...asset.materials,
+        ...asset.animations,
+    ].join(" ").toLowerCase();
+}
 function createAssetReadinessIssues(profile, asset) {
     if (asset.type !== "model")
         return { failures: [], warnings: [] };
@@ -1342,10 +1557,35 @@ function createAssetProvenance(projectDir, sourcePath, options, detected) {
         ...(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 } : {}),
+        ...(options.sha256 ?? detected?.sha256 ? { sha256: options.sha256 ?? detected?.sha256 } : {}),
+        ...(options.retrievedAt ?? detected?.retrievedAt ? { retrievedAt: options.retrievedAt ?? detected?.retrievedAt } : {}),
         ...(detected?.evidence && detected.evidence.length > 0 ? { evidence: detected.evidence } : {}),
         checkedAt: new Date().toISOString()
     };
 }
+/**
+ * Merge a freshly inspected asset's auto-detected provenance over the entry that
+ * already exists in the manifest, so a re-add/re-resolve preserves hand-authored
+ * fields (license, attribution, author, sourceUrl, sourceFamily, evidence,
+ * sha256) that the new pass did not re-detect. Freshly detected values win over
+ * the prior entry; explicit `addAsset` options still win over both (applied in
+ * {@link createAssetProvenance}). (#26)
+ */
+function mergeDetectedProvenance(existing, detected) {
+    if (!existing)
+        return detected;
+    const evidence = [...(detected?.evidence ?? []), ...(existing.evidence ?? [])];
+    return {
+        sourceUrl: detected?.sourceUrl ?? existing.sourceUrl,
+        license: detected?.license ?? existing.license,
+        author: detected?.author ?? existing.author,
+        sourceFamily: detected?.sourceFamily ?? existing.sourceFamily,
+        attribution: detected?.attribution ?? existing.attribution,
+        sha256: detected?.sha256 ?? existing.sha256,
+        retrievedAt: detected?.retrievedAt ?? existing.retrievedAt,
+        ...(evidence.length > 0 ? { evidence: [...new Set(evidence)] } : {})
+    };
+}
 function readExternalProvenance(projectDir, provenanceFile) {
     if (!provenanceFile)
         return new Map();
@@ -1375,6 +1615,8 @@ function readExternalProvenance(projectDir, provenanceFile) {
         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 sha256 = stringValue(record.sha256 ?? nestedProvenance?.sha256);
+        const retrievedAt = stringValue(record.retrievedAt ?? nestedProvenance?.retrievedAt);
         const evidence = [
             ...stringArrayValue(record.evidence),
             ...stringArrayValue(record.intendedRouteUsage),
@@ -1387,6 +1629,8 @@ function readExternalProvenance(projectDir, provenanceFile) {
             ...(author ? { author } : {}),
             ...(sourceFamily ? { sourceFamily } : {}),
             ...(attribution ? { attribution } : {}),
+            ...(sha256 ? { sha256 } : {}),
+            ...(retrievedAt ? { retrievedAt } : {}),
             ...(evidence.length > 0 ? { evidence } : {}),
             checkedAt
         });