lootforge 0.3.0

package/dist/checks/packInvariants.js

@@ -0,0 +1,1064 @@
+import { openImage } from "../shared/image.js";
+import { normalizeTargetOutPath, resolvePathWithinDir } from "../shared/paths.js";
+const BYTES_PER_MEGABYTE = 1024 * 1024;
+const SUBJECT_COLOR_DISTANCE_THRESHOLD = 18;
+const SUBJECT_ALPHA_DISTANCE_THRESHOLD = 12;
+const FACING_DESCRIPTOR_GRID_SIZE = 12;
+const FACING_MISMATCH_DELTA_MIN = 0.001;
+const FACING_MISMATCH_RATIO_MIN = 1.01;
+const FACING_ASSIGNMENT_IMPROVEMENT_MIN = 0.005;
+const UPPER_BODY_REGION = { minYRatio: 0, maxYRatio: 0.48 };
+const LOWER_BODY_REGION = { minYRatio: 0.48, maxYRatio: 0.84 };
+const FOOT_REGION = { minYRatio: 0.78, maxYRatio: 1 };
+export async function runPackInvariantChecks(params) {
+    const runtimeTargets = params.targets.filter((target) => target.catalogDisabled !== true);
+    const runtimeTargetIds = new Set(runtimeTargets.map((target) => target.id));
+    const targetsById = new Map(params.targets.map((target) => [target.id, target]));
+    const issues = [];
+    const targetIssues = [];
+    const continuityMetricsByAnimation = {};
+    const addIssue = (issue) => {
+        const normalizedTargetIds = Array.from(new Set(issue.targetIds));
+        if (normalizedTargetIds.length === 0) {
+            return;
+        }
+        const normalizedIssue = {
+            ...issue,
+            targetIds: normalizedTargetIds,
+        };
+        issues.push(normalizedIssue);
+        for (const targetId of normalizedTargetIds) {
+            if (!runtimeTargetIds.has(targetId)) {
+                continue;
+            }
+            targetIssues.push({
+                targetId,
+                level: normalizedIssue.level,
+                code: normalizedIssue.code,
+                message: normalizedIssue.message,
+            });
+        }
+    };
+    enforceRuntimeOutputUniqueness(runtimeTargets, addIssue);
+    const families = collectSpritesheetFamilies(params.targets);
+    for (const family of families.values()) {
+        await enforceSpritesheetFamilyInvariants({
+            family,
+            imagesDir: params.imagesDir,
+            addIssue,
+            continuityMetricsByAnimation,
+            runtimeTargetIds,
+            targetsById,
+        });
+    }
+    const textureBudgetMetricsByProfile = enforceTextureBudgetByProfile({
+        runtimeTargets,
+        items: params.items,
+        addIssue,
+    });
+    const metrics = {
+        ...(Object.keys(textureBudgetMetricsByProfile).length > 0
+            ? { textureBudgetMBByProfile: textureBudgetMetricsByProfile }
+            : {}),
+        ...(Object.keys(continuityMetricsByAnimation).length > 0
+            ? { spritesheetContinuityByAnimation: continuityMetricsByAnimation }
+            : {}),
+    };
+    const hasMetrics = Object.keys(metrics).length > 0;
+    const summary = issues.length > 0 || hasMetrics
+        ? {
+            errors: issues.filter((issue) => issue.level === "error").length,
+            warnings: issues.filter((issue) => issue.level === "warning").length,
+            issues,
+            ...(hasMetrics ? { metrics } : {}),
+        }
+        : undefined;
+    return {
+        summary,
+        targetIssues,
+    };
+}
+function enforceRuntimeOutputUniqueness(runtimeTargets, addIssue) {
+    const outPathToTargetIds = new Map();
+    for (const target of runtimeTargets) {
+        let normalizedOut;
+        try {
+            normalizedOut = normalizeTargetOutPath(target.out).toLowerCase();
+        }
+        catch {
+            continue;
+        }
+        const targetIds = outPathToTargetIds.get(normalizedOut) ?? new Set();
+        targetIds.add(target.id);
+        outPathToTargetIds.set(normalizedOut, targetIds);
+    }
+    for (const [normalizedOut, targetIds] of outPathToTargetIds) {
+        if (targetIds.size < 2) {
+            continue;
+        }
+        const duplicates = Array.from(targetIds).sort((left, right) => left.localeCompare(right));
+        addIssue({
+            level: "error",
+            code: "pack_duplicate_runtime_out",
+            message: `Runtime output collision for normalized path "${normalizedOut}" across targets: ${duplicates.join(", ")}.`,
+            targetIds: duplicates,
+        });
+    }
+}
+function collectSpritesheetFamilies(targets) {
+    const families = new Map();
+    for (const target of targets) {
+        const sheetTargetId = target.spritesheet?.sheetTargetId;
+        if (!sheetTargetId) {
+            continue;
+        }
+        const family = families.get(sheetTargetId) ?? {
+            id: sheetTargetId,
+            sheets: [],
+            frames: [],
+        };
+        if (target.spritesheet?.isSheet === true) {
+            family.sheets.push(target);
+        }
+        else {
+            family.frames.push(target);
+        }
+        families.set(sheetTargetId, family);
+    }
+    return families;
+}
+async function enforceSpritesheetFamilyInvariants(params) {
+    const { family } = params;
+    const sheetTargets = family.sheets;
+    const frameTargets = family.frames;
+    if (sheetTargets.length === 0 && frameTargets.length > 0) {
+        params.addIssue({
+            level: "error",
+            code: "spritesheet_missing_sheet_target",
+            message: `Spritesheet family "${family.id}" has frame targets but no sheet target.`,
+            targetIds: frameTargets.map((target) => target.id),
+        });
+        return;
+    }
+    if (sheetTargets.length > 1) {
+        params.addIssue({
+            level: "error",
+            code: "spritesheet_multiple_sheet_targets",
+            message: `Spritesheet family "${family.id}" has multiple sheet targets: ${sheetTargets
+                .map((target) => target.id)
+                .join(", ")}.`,
+            targetIds: sheetTargets.map((target) => target.id),
+        });
+    }
+    const sheetTarget = sheetTargets[0];
+    if (!sheetTarget) {
+        return;
+    }
+    if (sheetTarget.id !== family.id) {
+        params.addIssue({
+            level: "error",
+            code: "spritesheet_sheet_target_id_mismatch",
+            message: `Spritesheet sheet target "${sheetTarget.id}" does not match family id "${family.id}".`,
+            targetIds: [sheetTarget.id, ...frameTargets.map((target) => target.id)],
+        });
+    }
+    const sheetTargetId = sheetTarget.id;
+    const expectedAtlasGroup = normalizeAtlasGroup(sheetTarget.atlasGroup);
+    const mismatchedFrames = frameTargets.filter((frame) => normalizeAtlasGroup(frame.atlasGroup) !== expectedAtlasGroup);
+    if (mismatchedFrames.length > 0) {
+        params.addIssue({
+            level: "error",
+            code: "spritesheet_atlas_group_mismatch",
+            message: `Spritesheet family "${family.id}" has frame targets outside atlas group "${expectedAtlasGroup ?? "(none)"}".`,
+            targetIds: [sheetTargetId, ...mismatchedFrames.map((frame) => frame.id)],
+        });
+    }
+    const expectedAnimationCounts = new Map((sheetTarget.spritesheet?.animations ?? []).map((animation) => [
+        animation.name,
+        animation.count,
+    ]));
+    const framesByAnimation = new Map();
+    for (const frame of frameTargets) {
+        const animationName = frame.spritesheet?.animationName;
+        if (!animationName) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_frame_missing_animation_name",
+                message: `Frame target "${frame.id}" in family "${family.id}" is missing spritesheet.animationName.`,
+                targetIds: [sheetTargetId, frame.id],
+            });
+            continue;
+        }
+        const list = framesByAnimation.get(animationName) ?? [];
+        list.push(frame);
+        framesByAnimation.set(animationName, list);
+    }
+    for (const [animationName, expectedCount] of expectedAnimationCounts) {
+        const actualCount = framesByAnimation.get(animationName)?.length ?? 0;
+        if (actualCount !== expectedCount) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_frame_count_mismatch",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" expected ${expectedCount} frame(s) but found ${actualCount}.`,
+                targetIds: [
+                    sheetTargetId,
+                    ...(framesByAnimation.get(animationName) ?? []).map((frame) => frame.id),
+                ],
+            });
+        }
+    }
+    for (const [animationName, frames] of framesByAnimation) {
+        if (!expectedAnimationCounts.has(animationName)) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_unexpected_animation_frames",
+                message: `Spritesheet family "${family.id}" contains frames for unexpected animation "${animationName}".`,
+                targetIds: [sheetTargetId, ...frames.map((frame) => frame.id)],
+            });
+        }
+    }
+    const inspectedFrames = await inspectSpritesheetFrames({
+        frames: frameTargets,
+        imagesDir: params.imagesDir,
+        sheetTargetId,
+        addIssue: params.addIssue,
+        runtimeTargetIds: params.runtimeTargetIds,
+    });
+    if (inspectedFrames.size === 0) {
+        return;
+    }
+    for (const [animationName, frames] of framesByAnimation) {
+        const orderedFrames = [...frames].sort((left, right) => {
+            const leftIndex = left.spritesheet?.frameIndex ?? Number.MAX_SAFE_INTEGER;
+            const rightIndex = right.spritesheet?.frameIndex ?? Number.MAX_SAFE_INTEGER;
+            if (leftIndex !== rightIndex) {
+                return leftIndex - rightIndex;
+            }
+            return left.id.localeCompare(right.id);
+        });
+        if (orderedFrames.length < 2) {
+            continue;
+        }
+        let comparisons = 0;
+        let maxSilhouetteDrift = 0;
+        let maxAnchorDrift = 0;
+        let maxIdentityDrift = 0;
+        let maxPoseDrift = 0;
+        let maxUpperBodyMotionDrift = 0;
+        let maxLowerBodyMotionDrift = 0;
+        let maxFootMotionDrift = 0;
+        for (let index = 1; index < orderedFrames.length; index += 1) {
+            const previous = inspectedFrames.get(orderedFrames[index - 1].id);
+            const current = inspectedFrames.get(orderedFrames[index].id);
+            if (!previous || !current) {
+                continue;
+            }
+            if (previous.silhouette && current.silhouette) {
+                const silhouetteDrift = computeSilhouetteDrift(previous, current);
+                maxSilhouetteDrift = Math.max(maxSilhouetteDrift, silhouetteDrift);
+            }
+            const anchorDrift = computeAnchorDrift(previous, current);
+            maxAnchorDrift = Math.max(maxAnchorDrift, anchorDrift);
+            const identityDrift = computeIdentityDrift(previous, current);
+            maxIdentityDrift = Math.max(maxIdentityDrift, identityDrift);
+            const poseDrift = computePoseDrift(previous, current);
+            maxPoseDrift = Math.max(maxPoseDrift, poseDrift);
+            const upperBodyMotionDrift = computeRegionMotionDrift(previous.upperBodyDescriptor, current.upperBodyDescriptor);
+            maxUpperBodyMotionDrift = Math.max(maxUpperBodyMotionDrift, upperBodyMotionDrift);
+            const lowerBodyMotionDrift = computeRegionMotionDrift(previous.lowerBodyDescriptor, current.lowerBodyDescriptor);
+            maxLowerBodyMotionDrift = Math.max(maxLowerBodyMotionDrift, lowerBodyMotionDrift);
+            const footMotionDrift = computeRegionMotionDrift(previous.footDescriptor, current.footDescriptor);
+            maxFootMotionDrift = Math.max(maxFootMotionDrift, footMotionDrift);
+            comparisons += 1;
+        }
+        if (comparisons === 0) {
+            continue;
+        }
+        const continuityKey = `${sheetTargetId}:${animationName}`;
+        params.continuityMetricsByAnimation[continuityKey] = {
+            comparisons,
+            maxSilhouetteDrift: Number(maxSilhouetteDrift.toFixed(6)),
+            maxAnchorDrift: Number(maxAnchorDrift.toFixed(6)),
+            maxIdentityDrift: Number(maxIdentityDrift.toFixed(6)),
+            maxPoseDrift: Number(maxPoseDrift.toFixed(6)),
+            maxUpperBodyMotionDrift: Number(maxUpperBodyMotionDrift.toFixed(6)),
+            maxLowerBodyMotionDrift: Number(maxLowerBodyMotionDrift.toFixed(6)),
+            maxFootMotionDrift: Number(maxFootMotionDrift.toFixed(6)),
+        };
+        const silhouetteThreshold = resolveThresholdValue([
+            sheetTarget.spritesheetSilhouetteDriftMax,
+            ...orderedFrames.map((frame) => frame.spritesheetSilhouetteDriftMax),
+        ]);
+        if (typeof silhouetteThreshold === "number" && maxSilhouetteDrift > silhouetteThreshold) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_silhouette_drift_exceeded",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" exceeded silhouette drift threshold (${maxSilhouetteDrift.toFixed(4)} > ${silhouetteThreshold.toFixed(4)}).`,
+                targetIds: [sheetTargetId, ...orderedFrames.map((frame) => frame.id)],
+                metrics: {
+                    measured: Number(maxSilhouetteDrift.toFixed(6)),
+                    threshold: Number(silhouetteThreshold.toFixed(6)),
+                },
+            });
+        }
+        const anchorThreshold = resolveThresholdValue([
+            sheetTarget.spritesheetAnchorDriftMax,
+            ...orderedFrames.map((frame) => frame.spritesheetAnchorDriftMax),
+        ]);
+        if (typeof anchorThreshold === "number" && maxAnchorDrift > anchorThreshold) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_anchor_drift_exceeded",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" exceeded anchor drift threshold (${maxAnchorDrift.toFixed(4)} > ${anchorThreshold.toFixed(4)}).`,
+                targetIds: [sheetTargetId, ...orderedFrames.map((frame) => frame.id)],
+                metrics: {
+                    measured: Number(maxAnchorDrift.toFixed(6)),
+                    threshold: Number(anchorThreshold.toFixed(6)),
+                },
+            });
+        }
+        const identityThreshold = resolveThresholdValue([
+            sheetTarget.spritesheetIdentityDriftMax,
+            ...orderedFrames.map((frame) => frame.spritesheetIdentityDriftMax),
+        ]);
+        if (typeof identityThreshold === "number" && maxIdentityDrift > identityThreshold) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_identity_drift_exceeded",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" exceeded identity drift threshold (${maxIdentityDrift.toFixed(4)} > ${identityThreshold.toFixed(4)}).`,
+                targetIds: [sheetTargetId, ...orderedFrames.map((frame) => frame.id)],
+                metrics: {
+                    measured: Number(maxIdentityDrift.toFixed(6)),
+                    threshold: Number(identityThreshold.toFixed(6)),
+                },
+            });
+        }
+        const poseThreshold = resolveThresholdValue([
+            sheetTarget.spritesheetPoseDriftMax,
+            ...orderedFrames.map((frame) => frame.spritesheetPoseDriftMax),
+        ]);
+        if (typeof poseThreshold === "number" && maxPoseDrift > poseThreshold) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_pose_drift_exceeded",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" exceeded pose drift threshold (${maxPoseDrift.toFixed(4)} > ${poseThreshold.toFixed(4)}).`,
+                targetIds: [sheetTargetId, ...orderedFrames.map((frame) => frame.id)],
+                metrics: {
+                    measured: Number(maxPoseDrift.toFixed(6)),
+                    threshold: Number(poseThreshold.toFixed(6)),
+                },
+            });
+        }
+        const walkMotionViolation = resolveWalkCycleMotionViolation({
+            animationName,
+            sheetTarget,
+            orderedFrames,
+            maxUpperBodyMotionDrift,
+            maxLowerBodyMotionDrift,
+            maxFootMotionDrift,
+        });
+        if (walkMotionViolation) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_walk_cycle_motion_too_low",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" does not read as a walk cycle: ${walkMotionViolation.reason}.`,
+                targetIds: [sheetTargetId, ...orderedFrames.map((frame) => frame.id)],
+                metrics: walkMotionViolation.metrics,
+            });
+        }
+        const expectedFacing = resolveExpectedFacingDirection(sheetTarget, orderedFrames, animationName);
+        if (!expectedFacing) {
+            continue;
+        }
+        const animationInspections = orderedFrames
+            .map((frame) => inspectedFrames.get(frame.id))
+            .filter((inspection) => inspection !== undefined);
+        const facingConsistency = resolveFacingConsistencyViolation(animationInspections);
+        if (facingConsistency) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_facing_direction_inconsistent",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" contains mirrored-facing frames despite declared facing "${expectedFacing}".`,
+                targetIds: [sheetTargetId, ...facingConsistency.mismatchedFrameIds],
+                metrics: {
+                    improvement: Number(facingConsistency.improvement.toFixed(6)),
+                    mismatchedFrames: facingConsistency.mismatchedFrameIds.length,
+                },
+            });
+        }
+        const referenceTargets = resolveFacingReferenceTargets({
+            frames: orderedFrames,
+            sheetTarget,
+            targetsById: params.targetsById,
+            expectedFacing,
+        });
+        if (referenceTargets.length === 0) {
+            continue;
+        }
+        const referenceInspections = (await Promise.all(referenceTargets.map((target) => inspectTargetImage(target, params.imagesDir).catch(() => null)))).filter((inspection) => inspection !== null);
+        const facingMismatch = resolveFacingReferenceMismatch({
+            frames: animationInspections,
+            references: referenceInspections,
+        });
+        if (facingMismatch) {
+            params.addIssue({
+                level: "error",
+                code: "spritesheet_facing_direction_mismatch",
+                message: `Spritesheet animation "${animationName}" in family "${family.id}" drifted away from the declared "${expectedFacing}" facing relative to its reference sprite.`,
+                targetIds: [sheetTargetId, ...facingMismatch.mismatchedFrameIds],
+                metrics: {
+                    maxMirrorAdvantage: Number(facingMismatch.maxMirrorAdvantage.toFixed(6)),
+                    mismatchedFrames: facingMismatch.mismatchedFrameIds.length,
+                },
+            });
+        }
+    }
+}
+async function inspectSpritesheetFrames(params) {
+    const inspected = new Map();
+    for (const frame of params.frames) {
+        try {
+            normalizeTargetOutPath(frame.out);
+        }
+        catch (error) {
+            params.addIssue({
+                level: "warning",
+                code: "spritesheet_frame_path_invalid",
+                message: `Unable to normalize frame output path for "${frame.id}": ${error instanceof Error ? error.message : String(error)}`,
+                targetIds: [params.sheetTargetId, frame.id],
+            });
+            continue;
+        }
+        try {
+            const inspection = await inspectTargetImage(frame, params.imagesDir);
+            inspected.set(frame.id, inspection);
+        }
+        catch (error) {
+            params.addIssue({
+                level: "warning",
+                code: "spritesheet_frame_image_unavailable",
+                message: `Unable to inspect frame image for "${frame.id}": ${error instanceof Error ? error.message : String(error)}`,
+                targetIds: [params.sheetTargetId, frame.id].filter((targetId) => params.runtimeTargetIds.has(targetId)),
+            });
+        }
+    }
+    return inspected;
+}
+async function inspectTargetImage(target, imagesDir) {
+    const normalizedOut = normalizeTargetOutPath(target.out);
+    const imagePath = resolvePathWithinDir(imagesDir, normalizedOut, `target output for "${target.id}"`);
+    const raw = await openImage(imagePath, "qa")
+        .ensureAlpha()
+        .raw()
+        .toBuffer({ resolveWithObject: true });
+    const subjectMask = extractSubjectMask(raw.data, raw.info.channels, raw.info.width, raw.info.height);
+    const silhouette = extractMaskSilhouette(subjectMask, raw.info.width, raw.info.height);
+    return {
+        frame: target,
+        width: raw.info.width,
+        height: raw.info.height,
+        silhouette,
+        colorHistogram: computeVisibleColorHistogram(raw.data, raw.info.channels, subjectMask),
+        facingDescriptor: computeFacingDescriptor(raw.data, raw.info.channels, raw.info.width, raw.info.height, subjectMask, silhouette),
+        upperBodyDescriptor: computeMotionRegionDescriptor(raw.data, raw.info.channels, raw.info.width, raw.info.height, subjectMask, silhouette, UPPER_BODY_REGION),
+        lowerBodyDescriptor: computeMotionRegionDescriptor(raw.data, raw.info.channels, raw.info.width, raw.info.height, subjectMask, silhouette, LOWER_BODY_REGION),
+        footDescriptor: computeMotionRegionDescriptor(raw.data, raw.info.channels, raw.info.width, raw.info.height, subjectMask, silhouette, FOOT_REGION),
+    };
+}
+function extractSubjectMask(raw, channels, width, height) {
+    const mask = new Uint8Array(width * height);
+    if (channels < 4 || width <= 0 || height <= 0) {
+        return mask;
+    }
+    const background = estimateBackgroundColor(raw, channels, width, height);
+    let subjectPixels = 0;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const index = (y * width + x) * channels;
+            const alpha = raw[index + 3];
+            if (alpha <= 0) {
+                continue;
+            }
+            const colorDistance = Math.sqrt((raw[index] - background.r) ** 2 +
+                (raw[index + 1] - background.g) ** 2 +
+                (raw[index + 2] - background.b) ** 2);
+            const alphaDistance = Math.abs(alpha - background.a);
+            if (colorDistance > SUBJECT_COLOR_DISTANCE_THRESHOLD ||
+                alphaDistance > SUBJECT_ALPHA_DISTANCE_THRESHOLD) {
+                mask[y * width + x] = 1;
+                subjectPixels += 1;
+            }
+        }
+    }
+    if (subjectPixels > 0) {
+        return mask;
+    }
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const index = (y * width + x) * channels;
+            if (raw[index + 3] > 0) {
+                mask[y * width + x] = 1;
+            }
+        }
+    }
+    return mask;
+}
+function estimateBackgroundColor(raw, channels, width, height) {
+    const samplePoints = [
+        [0, 0],
+        [width - 1, 0],
+        [0, height - 1],
+        [width - 1, height - 1],
+        [Math.floor(width / 2), 0],
+        [Math.floor(width / 2), height - 1],
+        [0, Math.floor(height / 2)],
+        [width - 1, Math.floor(height / 2)],
+    ];
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let a = 0;
+    for (const [x, y] of samplePoints) {
+        const index = (y * width + x) * channels;
+        r += raw[index];
+        g += raw[index + 1];
+        b += raw[index + 2];
+        a += raw[index + 3];
+    }
+    return {
+        r: r / samplePoints.length,
+        g: g / samplePoints.length,
+        b: b / samplePoints.length,
+        a: a / samplePoints.length,
+    };
+}
+function extractMaskSilhouette(mask, width, height) {
+    if (width <= 0 || height <= 0) {
+        return null;
+    }
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let area = 0;
+    let sumX = 0;
+    let sumY = 0;
+    let sumXX = 0;
+    let sumYY = 0;
+    let sumXY = 0;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const index = y * width + x;
+            if (mask[index] === 0) {
+                continue;
+            }
+            area += 1;
+            sumX += x;
+            sumY += y;
+            sumXX += x * x;
+            sumYY += y * y;
+            sumXY += x * y;
+            if (x < minX)
+                minX = x;
+            if (y < minY)
+                minY = y;
+            if (x > maxX)
+                maxX = x;
+            if (y > maxY)
+                maxY = y;
+        }
+    }
+    if (area === 0) {
+        return null;
+    }
+    const meanX = sumX / area;
+    const meanY = sumY / area;
+    const covarianceXX = sumXX / area - meanX * meanX;
+    const covarianceYY = sumYY / area - meanY * meanY;
+    const covarianceXY = sumXY / area - meanX * meanY;
+    const orientationRadians = 0.5 * Math.atan2(2 * covarianceXY, covarianceXX - covarianceYY);
+    return {
+        minX,
+        minY,
+        maxX,
+        maxY,
+        area,
+        centerX: (minX + maxX) / 2,
+        centerY: (minY + maxY) / 2,
+        orientationRadians,
+    };
+}
+function computeSilhouetteDrift(left, right) {
+    if (!left.silhouette || !right.silhouette) {
+        return 0;
+    }
+    const diagonal = Math.max(Math.hypot(left.width, left.height), Math.hypot(right.width, right.height), 1);
+    const centerDelta = Math.hypot(left.silhouette.centerX - right.silhouette.centerX, left.silhouette.centerY - right.silhouette.centerY) / diagonal;
+    const areaDelta = Math.abs(left.silhouette.area - right.silhouette.area) /
+        Math.max(left.silhouette.area, right.silhouette.area, 1);
+    return (centerDelta + areaDelta) / 2;
+}
+function computeAnchorDrift(left, right) {
+    if (!left.silhouette || !right.silhouette) {
+        return 0;
+    }
+    const leftAnchor = resolveAnchorPoint(left);
+    const rightAnchor = resolveAnchorPoint(right);
+    const diagonal = Math.max(Math.hypot(left.width, left.height), Math.hypot(right.width, right.height), 1);
+    const leftVectorX = leftAnchor.x - left.silhouette.centerX;
+    const leftVectorY = leftAnchor.y - left.silhouette.centerY;
+    const rightVectorX = rightAnchor.x - right.silhouette.centerX;
+    const rightVectorY = rightAnchor.y - right.silhouette.centerY;
+    return Math.hypot(leftVectorX - rightVectorX, leftVectorY - rightVectorY) / diagonal;
+}
+function computeIdentityDrift(left, right) {
+    const distance = histogramDistance(left.colorHistogram, right.colorHistogram);
+    return Math.max(0, Math.min(1, distance / 2));
+}
+function computePoseDrift(left, right) {
+    if (!left.silhouette || !right.silhouette) {
+        return 0;
+    }
+    const delta = angularDistance(left.silhouette.orientationRadians, right.silhouette.orientationRadians);
+    return Math.max(0, Math.min(1, delta / Math.PI));
+}
+function computeRegionMotionDrift(left, right) {
+    if (!left || !right) {
+        return 0;
+    }
+    return computeFacingDescriptorDistance(left, right);
+}
+function resolveWalkCycleMotionViolation(params) {
+    if (params.animationName !== "walk") {
+        return null;
+    }
+    const lowerBodyMotionMin = resolveThresholdValue([
+        params.sheetTarget.spritesheetWalkLowerBodyMotionMin,
+        ...params.orderedFrames.map((frame) => frame.spritesheetWalkLowerBodyMotionMin),
+    ]);
+    const footMotionMin = resolveThresholdValue([
+        params.sheetTarget.spritesheetWalkFootMotionMin,
+        ...params.orderedFrames.map((frame) => frame.spritesheetWalkFootMotionMin),
+    ]);
+    const footToUpperMotionRatioMin = resolveThresholdValue([
+        params.sheetTarget.spritesheetWalkFootToUpperMotionRatioMin,
+        ...params.orderedFrames.map((frame) => frame.spritesheetWalkFootToUpperMotionRatioMin),
+    ]);
+    if (typeof lowerBodyMotionMin !== "number" &&
+        typeof footMotionMin !== "number" &&
+        typeof footToUpperMotionRatioMin !== "number") {
+        return null;
+    }
+    const footToUpperMotionRatio = params.maxFootMotionDrift / Math.max(params.maxUpperBodyMotionDrift, 1e-6);
+    const reasons = [];
+    const metrics = {
+        measuredUpperBodyMotion: Number(params.maxUpperBodyMotionDrift.toFixed(6)),
+        measuredLowerBodyMotion: Number(params.maxLowerBodyMotionDrift.toFixed(6)),
+        measuredFootMotion: Number(params.maxFootMotionDrift.toFixed(6)),
+        measuredFootToUpperRatio: Number(footToUpperMotionRatio.toFixed(6)),
+    };
+    if (typeof lowerBodyMotionMin === "number" &&
+        params.maxLowerBodyMotionDrift < lowerBodyMotionMin) {
+        reasons.push(`lower-body motion stayed too small (${params.maxLowerBodyMotionDrift.toFixed(4)} < ${lowerBodyMotionMin.toFixed(4)})`);
+        metrics.requiredLowerBodyMotion = Number(lowerBodyMotionMin.toFixed(6));
+    }
+    if (typeof footMotionMin === "number" && params.maxFootMotionDrift < footMotionMin) {
+        reasons.push(`foot motion stayed too small (${params.maxFootMotionDrift.toFixed(4)} < ${footMotionMin.toFixed(4)})`);
+        metrics.requiredFootMotion = Number(footMotionMin.toFixed(6));
+    }
+    if (typeof footToUpperMotionRatioMin === "number" &&
+        footToUpperMotionRatio < footToUpperMotionRatioMin) {
+        reasons.push(`foot motion was not meaningfully stronger than upper-body motion (${footToUpperMotionRatio.toFixed(4)} < ${footToUpperMotionRatioMin.toFixed(4)})`);
+        metrics.requiredFootToUpperRatio = Number(footToUpperMotionRatioMin.toFixed(6));
+    }
+    if (reasons.length === 0) {
+        return null;
+    }
+    return {
+        reason: reasons.join("; "),
+        metrics,
+    };
+}
+function resolveExpectedFacingDirection(sheetTarget, orderedFrames, animationName) {
+    const animationFacing = sheetTarget.spritesheet?.animations?.find((animation) => animation.name === animationName)?.facing;
+    if (animationFacing) {
+        return animationFacing;
+    }
+    for (const frame of orderedFrames) {
+        if (frame.spritesheet?.facing) {
+            return frame.spritesheet.facing;
+        }
+    }
+    return sheetTarget.facing;
+}
+function resolveFacingReferenceTargets(params) {
+    const orderedIds = [
+        ...(params.sheetTarget.styleReferenceFrom ?? []),
+        ...(params.sheetTarget.dependsOn ?? []),
+        ...params.frames.flatMap((frame) => [
+            ...(frame.styleReferenceFrom ?? []),
+            ...(frame.dependsOn ?? []),
+        ]),
+    ];
+    const references = [];
+    const seen = new Set();
+    for (const targetId of orderedIds) {
+        if (seen.has(targetId)) {
+            continue;
+        }
+        seen.add(targetId);
+        const target = params.targetsById.get(targetId);
+        if (target?.facing === params.expectedFacing && isExplicitFacingReferenceTarget(target)) {
+            references.push(target);
+        }
+    }
+    return references;
+}
+function resolveFacingConsistencyViolation(frames) {
+    const comparableFrames = frames.filter(hasFacingDescriptor);
+    if (comparableFrames.length < 2) {
+        return null;
+    }
+    const pairwise = buildPairwiseFacingDistances(comparableFrames);
+    const assignment = resolveBestFacingAssignment(pairwise);
+    if (!assignment || assignment.improvement < FACING_ASSIGNMENT_IMPROVEMENT_MIN) {
+        return null;
+    }
+    return {
+        mismatchedFrameIds: comparableFrames
+            .filter((_, index) => assignment.bits[index] === 1)
+            .map((frame) => frame.frame.id),
+        improvement: assignment.improvement,
+    };
+}
+function buildPairwiseFacingDistances(frames) {
+    return frames.map((left, leftIndex) => frames.map((right, rightIndex) => {
+        if (leftIndex === rightIndex) {
+            return { direct: 0, mirrored: 0 };
+        }
+        const leftDescriptor = left.facingDescriptor;
+        const rightDescriptor = right.facingDescriptor;
+        if (!leftDescriptor || !rightDescriptor) {
+            return { direct: Number.POSITIVE_INFINITY, mirrored: Number.POSITIVE_INFINITY };
+        }
+        return {
+            direct: computeFacingDescriptorDistance(leftDescriptor, rightDescriptor),
+            mirrored: computeFacingDescriptorDistance(leftDescriptor, flipFacingDescriptor(rightDescriptor)),
+        };
+    }));
+}
+function resolveBestFacingAssignment(pairwise) {
+    const frameCount = pairwise.length;
+    if (frameCount < 2) {
+        return null;
+    }
+    const baselineBits = new Array(frameCount).fill(0);
+    const baselineCost = computeFacingAssignmentCost(baselineBits, pairwise);
+    let bestBits = baselineBits;
+    let bestCost = baselineCost;
+    if (frameCount <= 12) {
+        const variants = 1 << (frameCount - 1);
+        for (let mask = 1; mask < variants; mask += 1) {
+            const bits = new Array(frameCount).fill(0);
+            for (let index = 1; index < frameCount; index += 1) {
+                bits[index] = (mask >> (index - 1)) & 1;
+            }
+            const cost = computeFacingAssignmentCost(bits, pairwise);
+            if (cost < bestCost) {
+                bestBits = bits;
+                bestCost = cost;
+            }
+        }
+    }
+    else {
+        const bits = new Array(frameCount).fill(0);
+        for (let index = 1; index < frameCount; index += 1) {
+            const distances = pairwise[0][index];
+            if (distances.mirrored < distances.direct) {
+                bits[index] = 1;
+            }
+        }
+        const cost = computeFacingAssignmentCost(bits, pairwise);
+        if (cost < bestCost) {
+            bestBits = bits;
+            bestCost = cost;
+        }
+    }
+    if (bestBits.every((bit) => bit === 0)) {
+        return null;
+    }
+    return {
+        bits: bestBits,
+        improvement: baselineCost - bestCost,
+    };
+}
+function computeFacingAssignmentCost(bits, pairwise) {
+    let total = 0;
+    for (let leftIndex = 0; leftIndex < bits.length; leftIndex += 1) {
+        for (let rightIndex = leftIndex + 1; rightIndex < bits.length; rightIndex += 1) {
+            const distances = pairwise[leftIndex][rightIndex];
+            total += bits[leftIndex] === bits[rightIndex] ? distances.direct : distances.mirrored;
+        }
+    }
+    return total;
+}
+function resolveFacingReferenceMismatch(params) {
+    const comparableFrames = params.frames.filter(hasFacingDescriptor);
+    const comparableReferences = params.references.filter(hasFacingDescriptor);
+    if (comparableFrames.length === 0 || comparableReferences.length === 0) {
+        return null;
+    }
+    const mismatchedFrameIds = [];
+    let maxMirrorAdvantage = 0;
+    for (const frame of comparableFrames) {
+        const descriptor = frame.facingDescriptor;
+        let bestDirect = Number.POSITIVE_INFINITY;
+        let bestMirrored = Number.POSITIVE_INFINITY;
+        for (const reference of comparableReferences) {
+            const referenceDescriptor = reference.facingDescriptor;
+            bestDirect = Math.min(bestDirect, computeFacingDescriptorDistance(referenceDescriptor, descriptor));
+            bestMirrored = Math.min(bestMirrored, computeFacingDescriptorDistance(referenceDescriptor, flipFacingDescriptor(descriptor)));
+        }
+        const mirrorAdvantage = bestDirect - bestMirrored;
+        maxMirrorAdvantage = Math.max(maxMirrorAdvantage, mirrorAdvantage);
+        if (bestDirect > bestMirrored + FACING_MISMATCH_DELTA_MIN &&
+            bestDirect / Math.max(bestMirrored, 1e-6) > FACING_MISMATCH_RATIO_MIN) {
+            mismatchedFrameIds.push(frame.frame.id);
+        }
+    }
+    if (mismatchedFrameIds.length === 0) {
+        return null;
+    }
+    return {
+        mismatchedFrameIds,
+        maxMirrorAdvantage,
+    };
+}
+function hasFacingDescriptor(frame) {
+    return frame.facingDescriptor !== null;
+}
+function isExplicitFacingReferenceTarget(target) {
+    const promptText = [
+        target.promptSpec.primary,
+        target.promptSpec.composition,
+        target.promptSpec.constraints,
+    ]
+        .filter((value) => typeof value === "string" && value.trim().length > 0)
+        .join(" ");
+    if (promptText.length === 0) {
+        return false;
+    }
+    return /\b(left-facing|right-facing|facing left|facing right|side[- ]profile|side view|profile view)\b/i.test(promptText);
+}
+function computeFacingDescriptor(raw, channels, width, height, subjectMask, silhouette) {
+    // TODO(agent): this uses shape/luminance heuristics; replace with a semantic pose/facing
+    // classifier if showcase captures still slip through or produce false positives.
+    return computeGridDescriptor(raw, channels, width, height, subjectMask, silhouette, {
+        minYRatio: 0,
+        maxYRatio: 1,
+    });
+}
+function computeMotionRegionDescriptor(raw, channels, width, height, subjectMask, silhouette, region) {
+    return computeGridDescriptor(raw, channels, width, height, subjectMask, silhouette, region);
+}
+function computeGridDescriptor(raw, channels, width, height, subjectMask, silhouette, region) {
+    if (!silhouette || width <= 0 || height <= 0) {
+        return null;
+    }
+    const bboxWidth = Math.max(1, silhouette.maxX - silhouette.minX + 1);
+    const bboxHeight = Math.max(1, silhouette.maxY - silhouette.minY + 1);
+    const regionMinY = Math.min(silhouette.maxY, silhouette.minY + Math.floor((bboxHeight - 1) * clamp01(region.minYRatio)));
+    const regionMaxY = Math.max(regionMinY, Math.min(silhouette.maxY, silhouette.minY + Math.ceil(bboxHeight * clamp01(region.maxYRatio)) - 1));
+    const regionHeight = Math.max(1, regionMaxY - regionMinY + 1);
+    const alphaGrid = new Array(FACING_DESCRIPTOR_GRID_SIZE ** 2).fill(0);
+    const luminanceGrid = new Array(FACING_DESCRIPTOR_GRID_SIZE ** 2).fill(0);
+    const cellCounts = new Array(FACING_DESCRIPTOR_GRID_SIZE ** 2).fill(0);
+    let subjectPixels = 0;
+    for (let y = regionMinY; y <= regionMaxY; y += 1) {
+        for (let x = silhouette.minX; x <= silhouette.maxX; x += 1) {
+            if (subjectMask[y * width + x] === 0) {
+                continue;
+            }
+            const gridX = Math.min(FACING_DESCRIPTOR_GRID_SIZE - 1, Math.floor(((x - silhouette.minX) * FACING_DESCRIPTOR_GRID_SIZE) / bboxWidth));
+            const gridY = Math.min(FACING_DESCRIPTOR_GRID_SIZE - 1, Math.floor(((y - regionMinY) * FACING_DESCRIPTOR_GRID_SIZE) / regionHeight));
+            const gridIndex = gridY * FACING_DESCRIPTOR_GRID_SIZE + gridX;
+            const rawIndex = (y * width + x) * channels;
+            alphaGrid[gridIndex] += 1;
+            luminanceGrid[gridIndex] +=
+                0.2126 * raw[rawIndex] + 0.7152 * raw[rawIndex + 1] + 0.0722 * raw[rawIndex + 2];
+            cellCounts[gridIndex] += 1;
+            subjectPixels += 1;
+        }
+    }
+    if (subjectPixels === 0) {
+        return null;
+    }
+    return {
+        gridSize: FACING_DESCRIPTOR_GRID_SIZE,
+        alphaGrid: alphaGrid.map((value) => value / subjectPixels),
+        luminanceGrid: luminanceGrid.map((value, index) => cellCounts[index] > 0 ? value / cellCounts[index] / 255 : 0),
+    };
+}
+function flipFacingDescriptor(descriptor) {
+    const alphaGrid = new Array(descriptor.alphaGrid.length).fill(0);
+    const luminanceGrid = new Array(descriptor.luminanceGrid.length).fill(0);
+    for (let y = 0; y < descriptor.gridSize; y += 1) {
+        for (let x = 0; x < descriptor.gridSize; x += 1) {
+            const sourceIndex = y * descriptor.gridSize + (descriptor.gridSize - 1 - x);
+            const targetIndex = y * descriptor.gridSize + x;
+            alphaGrid[targetIndex] = descriptor.alphaGrid[sourceIndex] ?? 0;
+            luminanceGrid[targetIndex] = descriptor.luminanceGrid[sourceIndex] ?? 0;
+        }
+    }
+    return {
+        gridSize: descriptor.gridSize,
+        alphaGrid,
+        luminanceGrid,
+    };
+}
+function computeFacingDescriptorDistance(left, right) {
+    const length = Math.max(left.alphaGrid.length, right.alphaGrid.length);
+    let distance = 0;
+    for (let index = 0; index < length; index += 1) {
+        distance +=
+            Math.abs((left.alphaGrid[index] ?? 0) - (right.alphaGrid[index] ?? 0)) * 0.7 +
+                Math.abs((left.luminanceGrid[index] ?? 0) - (right.luminanceGrid[index] ?? 0)) * 0.3;
+    }
+    return distance / Math.max(length, 1);
+}
+function angularDistance(a, b) {
+    let delta = Math.abs(a - b);
+    while (delta > Math.PI) {
+        delta -= Math.PI;
+    }
+    return Math.abs(delta);
+}
+function computeVisibleColorHistogram(raw, channels, subjectMask, bins = 8) {
+    const histogram = new Array(bins * bins * bins).fill(0);
+    let visibleCount = 0;
+    const channelToBin = (value) => Math.max(0, Math.min(bins - 1, Math.floor((value / 256) * bins)));
+    for (let index = 0; index < raw.length; index += channels) {
+        if (subjectMask[index / channels] === 0) {
+            continue;
+        }
+        const rBin = channelToBin(raw[index]);
+        const gBin = channelToBin(raw[index + 1]);
+        const bBin = channelToBin(raw[index + 2]);
+        const histogramIndex = rBin * bins * bins + gBin * bins + bBin;
+        histogram[histogramIndex] += 1;
+        visibleCount += 1;
+    }
+    if (visibleCount === 0) {
+        return histogram;
+    }
+    return histogram.map((value) => value / visibleCount);
+}
+function histogramDistance(left, right) {
+    const length = Math.max(left.length, right.length);
+    let distance = 0;
+    for (let index = 0; index < length; index += 1) {
+        distance += Math.abs((left[index] ?? 0) - (right[index] ?? 0));
+    }
+    return distance;
+}
+function resolveAnchorPoint(frame) {
+    const pivot = frame.frame.spritesheet?.pivot;
+    const normalizedPivot = {
+        x: clamp01(pivot?.x ?? 0.5),
+        y: clamp01(pivot?.y ?? 0.5),
+    };
+    return {
+        x: normalizedPivot.x * frame.width,
+        y: normalizedPivot.y * frame.height,
+    };
+}
+function clamp01(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    if (value < 0) {
+        return 0;
+    }
+    if (value > 1) {
+        return 1;
+    }
+    return value;
+}
+function resolveThresholdValue(values) {
+    for (const value of values) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function enforceTextureBudgetByProfile(params) {
+    const metricsByProfile = {};
+    const itemByTargetId = new Map(params.items.map((item) => [item.targetId, item]));
+    const profileStats = new Map();
+    for (const target of params.runtimeTargets) {
+        const profileId = target.evaluationProfileId ?? "__default__";
+        const entry = profileStats.get(profileId) ?? {
+            targetIds: new Set(),
+            estimatedBytes: 0,
+            budgetMB: undefined,
+            hasMismatchedBudget: false,
+        };
+        entry.targetIds.add(target.id);
+        const item = itemByTargetId.get(target.id);
+        const width = item?.width;
+        const height = item?.height;
+        if (typeof width === "number" && typeof height === "number") {
+            entry.estimatedBytes += width * height * 4;
+        }
+        const budgetMB = target.packTextureBudgetMB;
+        if (typeof budgetMB === "number") {
+            if (typeof entry.budgetMB === "number" && Math.abs(entry.budgetMB - budgetMB) > 1e-6) {
+                entry.hasMismatchedBudget = true;
+            }
+            entry.budgetMB = Math.min(entry.budgetMB ?? budgetMB, budgetMB);
+        }
+        profileStats.set(profileId, entry);
+    }
+    for (const [profileId, entry] of profileStats) {
+        const estimatedMB = entry.estimatedBytes / BYTES_PER_MEGABYTE;
+        metricsByProfile[profileId] = {
+            estimatedMB: Number(estimatedMB.toFixed(6)),
+            ...(typeof entry.budgetMB === "number"
+                ? { budgetMB: Number(entry.budgetMB.toFixed(6)) }
+                : {}),
+            targetCount: entry.targetIds.size,
+        };
+        if (entry.hasMismatchedBudget) {
+            params.addIssue({
+                level: "warning",
+                code: "pack_texture_budget_profile_mismatch",
+                message: `Evaluation profile "${profileId}" resolved conflicting packTextureBudgetMB values across targets.`,
+                targetIds: Array.from(entry.targetIds),
+                evaluationProfileId: profileId,
+            });
+        }
+        if (typeof entry.budgetMB === "number" && estimatedMB > entry.budgetMB) {
+            params.addIssue({
+                level: "error",
+                code: "pack_texture_budget_exceeded",
+                message: `Evaluation profile "${profileId}" estimated texture memory ${estimatedMB.toFixed(2)}MB exceeds configured budget ${entry.budgetMB.toFixed(2)}MB.`,
+                targetIds: Array.from(entry.targetIds),
+                evaluationProfileId: profileId,
+                metrics: {
+                    estimatedMB: Number(estimatedMB.toFixed(6)),
+                    budgetMB: Number(entry.budgetMB.toFixed(6)),
+                },
+            });
+        }
+    }
+    return metricsByProfile;
+}
+function normalizeAtlasGroup(value) {
+    if (!value) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+//# sourceMappingURL=packInvariants.js.map