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

package/dist/world/analyze.js

@@ -0,0 +1,767 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHelperType = exports.isCharacterSubtree = exports.STEP_HEIGHT_M = void 0;
+exports.rotateByQuat = rotateByQuat;
+exports.colliderAabb = colliderAabb;
+exports.yawDeg = yawDeg;
+exports.obbPenetration = obbPenetration;
+exports.analyzeWorld = analyzeWorld;
+exports.sortFindings = sortFindings;
+exports.reachabilityRule = reachabilityRule;
+// Thresholds — hardcoded mirrors of humanoid-character's traversal defaults (RapierBody:
+// autostep maxHeight 0.35 m, capsule 1.80 m × r 0.30). A future world_metrics table supersedes
+// these; until then keep the values in sync with RapierBody's option defaults.
+exports.STEP_HEIGHT_M = 0.35;
+const SINK_TOLERANCE_M = 0.05;
+const INTERSECT_TOLERANCE_M = 0.05;
+const FLOOR_EPSILON_M = 0.02;
+// A support this tall is often a ramp/terrain whose AABB top is its peak — the gap measured
+// against it misreads slopes, so support-based findings drop to low confidence.
+const TALL_SUPPORT_M = 1.0;
+const DIVERGENCE_RATIO = 1.25;
+const DIVERGENCE_OFFSET_M = 0.25;
+// A collider only "belongs to" a visual it actually touches — per-axis gap beyond this and the
+// pair is not a proxy relationship (obby's kill-plane band vs the pit floor 1.5 m below it).
+const MATCH_GAP_M = 0.1;
+const HALF_EXTENT_SLIP_RATIO = 2;
+const RATIO_EPS = 0.06;
+const ORPHAN_VISUAL_MIN_VOLUME_M3 = 0.5;
+const OFF_GRID_MIN_SIBLINGS = 3;
+const OFF_GRID_SHARE = 0.8;
+const OFF_GRID_TOLERANCE_DEG = 1.0;
+const GRIDS_DEG = [90, 45, 30, 15];
+const OUT_OF_BOUNDS_FACTOR = 5;
+const OUT_OF_BOUNDS_MIN_M = 50;
+const DEGENERATE_SCALE = 1e-4;
+const r2 = (n) => Math.round(n * 100) / 100;
+function rotateByQuat(v, q) {
+    // v' = v + 2q×(q×v + wv) — standard quaternion-vector rotation without a matrix.
+    const tx = 2 * (q.y * v.z - q.z * v.y);
+    const ty = 2 * (q.z * v.x - q.x * v.z);
+    const tz = 2 * (q.x * v.y - q.y * v.x);
+    return {
+        x: v.x + q.w * tx + (q.y * tz - q.z * ty),
+        y: v.y + q.w * ty + (q.z * tx - q.x * tz),
+        z: v.z + q.w * tz + (q.x * ty - q.y * tx),
+    };
+}
+// AABB of a rotated box/ball/capsule collider. Trimeshes have no extents in the snapshot and
+// return null — they are exempt from extent-based matching.
+function colliderAabb(c) {
+    let half = null;
+    if (c.halfExtents)
+        half = c.halfExtents;
+    else if (typeof c.radius === 'number' && typeof c.halfHeight === 'number')
+        half = { x: c.radius, y: c.halfHeight + c.radius, z: c.radius };
+    else if (typeof c.radius === 'number')
+        half = { x: c.radius, y: c.radius, z: c.radius };
+    if (!half)
+        return null;
+    const min = { x: Infinity, y: Infinity, z: Infinity };
+    const max = { x: -Infinity, y: -Infinity, z: -Infinity };
+    for (const sx of [-1, 1]) {
+        for (const sy of [-1, 1]) {
+            for (const sz of [-1, 1]) {
+                const corner = rotateByQuat({ x: half.x * sx, y: half.y * sy, z: half.z * sz }, c.rotation);
+                const wx = c.position.x + corner.x;
+                const wy = c.position.y + corner.y;
+                const wz = c.position.z + corner.z;
+                if (wx < min.x)
+                    min.x = wx;
+                if (wy < min.y)
+                    min.y = wy;
+                if (wz < min.z)
+                    min.z = wz;
+                if (wx > max.x)
+                    max.x = wx;
+                if (wy > max.y)
+                    max.y = wy;
+                if (wz > max.z)
+                    max.z = wz;
+            }
+        }
+    }
+    return { min, max };
+}
+const size = (b) => ({ x: b.max.x - b.min.x, y: b.max.y - b.min.y, z: b.max.z - b.min.z });
+const center = (b) => ({
+    x: (b.min.x + b.max.x) / 2,
+    y: (b.min.y + b.max.y) / 2,
+    z: (b.min.z + b.max.z) / 2,
+});
+const volume = (b) => {
+    const s = size(b);
+    return s.x * s.y * s.z;
+};
+const xzOverlaps = (a, b) => a.min.x < b.max.x && a.max.x > b.min.x && a.min.z < b.max.z && a.max.z > b.min.z;
+const contains = (outer, inner) => outer.min.x <= inner.min.x &&
+    outer.min.y <= inner.min.y &&
+    outer.min.z <= inner.min.z &&
+    outer.max.x >= inner.max.x &&
+    outer.max.y >= inner.max.y &&
+    outer.max.z >= inner.max.z;
+/** Yaw about +Y in degrees, [0, 360). */
+function yawDeg(q) {
+    const deg = (Math.atan2(2 * (q.w * q.y + q.x * q.z), 1 - 2 * (q.y * q.y + q.z * q.z)) * 180) / Math.PI;
+    return ((deg % 360) + 360) % 360;
+}
+// The character system's own model (humanoid-character names its LOD group "character-lod"): its
+// internal anatomy — co-located LOD levels, body/face overlap — is not world layout. Excluded
+// from placement rules; still in the roster and still checked for degenerate transforms.
+const isCharacterSubtree = (path) => path.split('/').includes('character-lod');
+exports.isCharacterSubtree = isCharacterSubtree;
+// Lines and point clouds are debug/FX helpers (path viz, grids), not renderable surfaces — they
+// neither rest, support, nor collide, and toggling them off is normal.
+const isHelperType = (type) => /^(Line|Points)/.test(type);
+exports.isHelperType = isHelperType;
+const parentOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
+// Two siblings inside a non-root group are parts of one authored composite (a turret stacked from
+// primitives); their mutual overlap is construction, not layout. Root-level siblings ARE layout.
+const isCompositePair = (pathA, pathB) => {
+    const parent = parentOf(pathA);
+    return parent !== '' && parent === parentOf(pathB);
+};
+const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+function obbOf(obj) {
+    if (!obj.obb)
+        return null;
+    const q = obj.rotation;
+    return {
+        center: obj.obb.center,
+        half: obj.obb.half,
+        axes: [rotateByQuat({ x: 1, y: 0, z: 0 }, q), rotateByQuat({ x: 0, y: 1, z: 0 }, q), rotateByQuat({ x: 0, y: 0, z: 1 }, q)],
+    };
+}
+// Separating-axis penetration for two OBBs: the min overlap across the 15 candidate axes, or
+// null when any axis separates them. Face axes alone miss edge-edge contact; the 9 cross
+// products cover it.
+function obbPenetration(a, b) {
+    const axes = [...a.axes, ...b.axes];
+    for (const u of a.axes) {
+        for (const v of b.axes) {
+            const c = { x: u.y * v.z - u.z * v.y, y: u.z * v.x - u.x * v.z, z: u.x * v.y - u.y * v.x };
+            const len = Math.hypot(c.x, c.y, c.z);
+            if (len > 1e-6)
+                axes.push({ x: c.x / len, y: c.y / len, z: c.z / len });
+        }
+    }
+    const d = { x: b.center.x - a.center.x, y: b.center.y - a.center.y, z: b.center.z - a.center.z };
+    let minOverlap = Infinity;
+    for (const axis of axes) {
+        const ra = a.half.x * Math.abs(dot(axis, a.axes[0])) + a.half.y * Math.abs(dot(axis, a.axes[1])) + a.half.z * Math.abs(dot(axis, a.axes[2]));
+        const rb = b.half.x * Math.abs(dot(axis, b.axes[0])) + b.half.y * Math.abs(dot(axis, b.axes[1])) + b.half.z * Math.abs(dot(axis, b.axes[2]));
+        const overlap = ra + rb - Math.abs(dot(d, axis));
+        if (overlap <= 0)
+            return null;
+        if (overlap < minOverlap)
+            minOverlap = overlap;
+    }
+    return minOverlap;
+}
+function supportRules(items, colliders, findings) {
+    // Invisible meshes (LOD levels, toggled variants) neither rest on anything nor support
+    // anything visually — both sides of the rule consider visible geometry only. Colliders
+    // always count: an invisible floor collider is a legitimate support.
+    const visibleItems = items.filter((i) => i.obj.visible);
+    const surfaces = [
+        ...visibleItems.map((i) => ({ top: i.aabb.max.y, span: i.aabb.max.y - i.aabb.min.y, label: i.obj.path, aabb: i.aabb })),
+        ...colliders
+            .map((c, index) => ({ index, aabb: colliderAabb(c) }))
+            .filter((x) => x.aabb !== null)
+            .map(({ index, aabb }) => ({ top: aabb.max.y, span: aabb.max.y - aabb.min.y, label: `collider[${index}]`, aabb })),
+    ];
+    if (visibleItems.length === 0)
+        return;
+    const floorY = Math.min(...visibleItems.map((i) => i.aabb.min.y));
+    const pending = [];
+    for (const item of visibleItems) {
+        const { aabb, obj } = item;
+        if (aabb.min.y <= floorY + FLOOR_EPSILON_M)
+            continue; // this IS (part of) the scene floor
+        // Support = the highest XZ-overlapping surface whose top sits at or below the object's top;
+        // walls beside the footprint don't overlap in XZ, ceilings above are excluded by the top test.
+        let support = null;
+        for (const s of surfaces) {
+            if (s.label === obj.path)
+                continue;
+            if (s.top > aabb.max.y)
+                continue;
+            if (!xzOverlaps(aabb, s.aabb))
+                continue;
+            if (!support || s.top > support.top)
+                support = s;
+        }
+        if (!support) {
+            const gap = aabb.min.y - floorY;
+            if (gap > exports.STEP_HEIGHT_M) {
+                pending.push({
+                    parent: parentOf(obj.path),
+                    supportLabel: 'the scene floor',
+                    gap: r2(gap),
+                    finding: {
+                        rule: 'floating',
+                        severity: 'warn',
+                        path: obj.path,
+                        detail: `floating ${r2(gap)} m above the scene floor (no surface beneath its footprint)`,
+                        measured: { gapM: r2(gap) },
+                        method: 'AABB min.y vs the lowest AABB in the scene; no XZ-overlapping support found',
+                        confidence: 'medium',
+                    },
+                });
+            }
+            continue;
+        }
+        const gap = aabb.min.y - support.top;
+        const confidence = support.span > TALL_SUPPORT_M ? 'low' : 'medium';
+        const slopeCaveat = support.span > TALL_SUPPORT_M ? ' (support is tall — a ramp/terrain AABB top is its peak, so this may misread)' : '';
+        if (gap > exports.STEP_HEIGHT_M) {
+            pending.push({
+                parent: parentOf(obj.path),
+                supportLabel: support.label,
+                gap: r2(gap),
+                finding: {
+                    rule: 'floating',
+                    severity: 'warn',
+                    path: obj.path,
+                    detail: `floating ${r2(gap)} m above ${support.label}${slopeCaveat}`,
+                    measured: { gapM: r2(gap) },
+                    method: `AABB min.y vs support AABB top; threshold = step height ${exports.STEP_HEIGHT_M} m`,
+                    confidence,
+                },
+            });
+        }
+        else if (gap < -SINK_TOLERANCE_M) {
+            // Near-full burial is not "sunk a bit into its floor": either the surface is the object's
+            // own co-located collision proxy, or the overlap is intersecting's domain.
+            const height = aabb.max.y - aabb.min.y;
+            if (-gap >= height * 0.95)
+                continue;
+            const composite = !support.label.startsWith('collider[') && isCompositePair(obj.path, support.label);
+            pending.push({
+                parent: parentOf(obj.path),
+                supportLabel: support.label,
+                gap: r2(-gap),
+                finding: {
+                    rule: 'sunk',
+                    severity: composite ? 'info' : 'warn',
+                    path: obj.path,
+                    detail: `sunk ${r2(-gap)} m into ${support.label}${slopeCaveat}${composite ? ' (composite model internals)' : ''}`,
+                    measured: { penetrationM: r2(-gap) },
+                    method: `AABB min.y below support AABB top; tolerance ${SINK_TOLERANCE_M} m`,
+                    confidence,
+                },
+            });
+        }
+    }
+    emitSupportRuns(pending, findings);
+}
+const RUN_COLLAPSE_MIN = 3;
+const RUN_BAND_M = 0.5;
+// Same parent + same rule/severity + same support → a run. Members within ±RUN_BAND_M of the run's
+// median gap collapse to one summary (range preserved); members outside the band stay individual —
+// in a hanging run, the bulb 2 m below its siblings is the finding worth reading.
+function emitSupportRuns(pending, findings) {
+    const groups = new Map();
+    for (const p of pending) {
+        const key = `${p.finding.rule}|${p.finding.severity}|${p.parent}|${p.supportLabel}`;
+        const list = groups.get(key) ?? [];
+        list.push(p);
+        groups.set(key, list);
+    }
+    for (const group of groups.values()) {
+        if (group.length < RUN_COLLAPSE_MIN) {
+            for (const p of group)
+                findings.push(p.finding);
+            continue;
+        }
+        const gaps = group.map((p) => p.gap).sort((a, b) => a - b);
+        const median = gaps[Math.floor(gaps.length / 2)];
+        const inliers = group.filter((p) => Math.abs(p.gap - median) <= RUN_BAND_M);
+        const outliers = group.filter((p) => Math.abs(p.gap - median) > RUN_BAND_M);
+        for (const p of outliers)
+            findings.push(p.finding);
+        if (inliers.length < RUN_COLLAPSE_MIN) {
+            for (const p of inliers)
+                findings.push(p.finding);
+            continue;
+        }
+        const first = inliers[0];
+        const min = Math.min(...inliers.map((p) => p.gap));
+        const max = Math.max(...inliers.map((p) => p.gap));
+        const verb = first.finding.rule === 'floating' ? 'floating' : 'sunk';
+        const prep = first.finding.rule === 'floating' ? 'above' : 'into';
+        const range = min === max ? `${min}` : `${min}–${max}`;
+        const parentLabel = first.parent === '' ? 'the scene root' : first.parent;
+        findings.push({
+            rule: first.finding.rule,
+            severity: first.finding.severity,
+            path: first.parent === '' ? first.finding.path : first.parent,
+            detail: `${inliers.length} children of ${parentLabel} ${verb} ${range} m ${prep} ${first.supportLabel} ` +
+                `(e.g. ${first.finding.path}) — a uniform same-parent run; adjudicate as one`,
+            measured: { children: inliers.length, gapMinM: min, gapMaxM: max },
+            method: 'same-parent same-support run collapse of individual support findings',
+            confidence: first.finding.confidence,
+        });
+    }
+}
+function intersectionRule(items, findings) {
+    // Sweep-prune on x so big rosters stay tractable; invisible objects don't visually intersect.
+    const visible = items.filter((i) => i.obj.visible).sort((a, b) => a.aabb.min.x - b.aabb.min.x);
+    for (let i = 0; i < visible.length; i++) {
+        const a = visible[i];
+        for (let j = i + 1; j < visible.length; j++) {
+            const b = visible[j];
+            if (b.aabb.min.x > a.aabb.max.x - INTERSECT_TOLERANCE_M)
+                break;
+            const dx = Math.min(a.aabb.max.x, b.aabb.max.x) - Math.max(a.aabb.min.x, b.aabb.min.x);
+            const dy = Math.min(a.aabb.max.y, b.aabb.max.y) - Math.max(a.aabb.min.y, b.aabb.min.y);
+            const dz = Math.min(a.aabb.max.z, b.aabb.max.z) - Math.max(a.aabb.min.z, b.aabb.min.z);
+            if (dx <= INTERSECT_TOLERANCE_M || dy <= INTERSECT_TOLERANCE_M || dz <= INTERSECT_TOLERANCE_M)
+                continue;
+            // Full containment is normal scene structure (a room shell contains its furniture) — skip.
+            if (contains(a.aabb, b.aabb) || contains(b.aabb, a.aabb))
+                continue;
+            // The AABB of rotated geometry is fat — where oriented boxes exist, the separating-axis
+            // test decides, so diagonal skirts/ramps stop flagging against everything beside them.
+            const obbA = obbOf(a.obj);
+            const obbB = obbOf(b.obj);
+            const composite = isCompositePair(a.obj.path, b.obj.path);
+            if (obbA && obbB) {
+                const penetration = obbPenetration(obbA, obbB);
+                if (penetration === null || penetration <= INTERSECT_TOLERANCE_M)
+                    continue;
+                findings.push({
+                    rule: 'intersecting',
+                    severity: composite ? 'info' : 'warn',
+                    path: a.obj.path,
+                    detail: `overlaps ${b.obj.path} — ${r2(penetration)} m deep at the tightest axis${composite ? ' (composite model internals)' : ''}`,
+                    measured: { penetrationM: r2(penetration) },
+                    method: 'oriented-box separating-axis test (bounding boxes; non-box shapes still over-approximate)',
+                    confidence: 'medium',
+                });
+                continue;
+            }
+            findings.push({
+                rule: 'intersecting',
+                severity: composite ? 'info' : 'warn',
+                path: a.obj.path,
+                detail: `overlaps ${b.obj.path} by ${r2(dx)}×${r2(dy)}×${r2(dz)} m${composite ? ' (composite model internals)' : ''}`,
+                measured: { dxM: r2(dx), dyM: r2(dy), dzM: r2(dz) },
+                method: 'pairwise AABB overlap on all 3 axes — AABB-only, non-box shapes false-positive in corners',
+                confidence: 'medium',
+            });
+        }
+    }
+}
+function colliderRules(items, colliders, findings) {
+    // Rapier handles are opaque f64 bit-packs (they print as denormals like 5e-324) — label
+    // colliders by roster ordinal everywhere a human reads them; the handle stays in the JSON.
+    const matchable = colliders
+        .map((c, index) => ({ c, index, aabb: colliderAabb(c) }))
+        .filter((x) => x.aabb !== null);
+    const matchedVisuals = new Set();
+    for (const { c, index, aabb } of matchable) {
+        const cCenter = center(aabb);
+        const cSize = size(aabb);
+        const cDiag = Math.hypot(cSize.x, cSize.y, cSize.z) / 2;
+        let best = null;
+        for (const item of items) {
+            // A proxy collider touches its visual: per-axis gap beyond MATCH_GAP_M disqualifies the
+            // pair even when centers are near (a kill-band plane hovering over a pit floor is not a proxy).
+            const gapX = Math.max(item.aabb.min.x - aabb.max.x, aabb.min.x - item.aabb.max.x, 0);
+            const gapY = Math.max(item.aabb.min.y - aabb.max.y, aabb.min.y - item.aabb.max.y, 0);
+            const gapZ = Math.max(item.aabb.min.z - aabb.max.z, aabb.min.z - item.aabb.max.z, 0);
+            if (gapX > MATCH_GAP_M || gapY > MATCH_GAP_M || gapZ > MATCH_GAP_M)
+                continue;
+            const vCenter = center(item.aabb);
+            const vSize = size(item.aabb);
+            const dist = Math.hypot(vCenter.x - cCenter.x, vCenter.y - cCenter.y, vCenter.z - cCenter.z);
+            if (dist > cDiag + Math.hypot(vSize.x, vSize.y, vSize.z) / 2)
+                continue;
+            if (!best || dist < best.dist)
+                best = { item, dist };
+        }
+        if (!best) {
+            findings.push({
+                rule: 'orphan-collider',
+                severity: 'info',
+                path: `collider[${index}]`,
+                detail: `${c.shape} collider at (${r2(c.position.x)}, ${r2(c.position.y)}, ${r2(c.position.z)}) matches no visual — invisible wall, or a visual that was moved without its collider`,
+                method: 'no visual AABB within combined half-diagonal reach',
+                confidence: 'medium',
+            });
+            continue;
+        }
+        matchedVisuals.add(best.item.obj.path);
+        const vSize = size(best.item.aabb);
+        const ratios = [cSize.x / vSize.x, cSize.y / vSize.y, cSize.z / vSize.z].map((r) => Number.isFinite(r) ? r : 1);
+        const isSlip = ratios.every((r) => Math.abs(r - HALF_EXTENT_SLIP_RATIO) <= RATIO_EPS * HALF_EXTENT_SLIP_RATIO);
+        if (isSlip) {
+            findings.push({
+                rule: 'collider-divergence',
+                severity: 'error',
+                path: best.item.obj.path,
+                detail: `collider[${index}] is exactly 2× this visual on every axis — half-extent/full-size slip (full sizes passed where half-extents belong)`,
+                measured: { rx: r2(ratios[0]), ry: r2(ratios[1]), rz: r2(ratios[2]) },
+                method: 'collider/visual AABB extent ratio ≈ 2 on all axes',
+                confidence: 'high',
+            });
+            continue;
+        }
+        const maxRatio = Math.max(...ratios.map((r) => Math.max(r, 1 / r)));
+        // A center offset explained by extent asymmetry is normal authoring: a thick floor collider
+        // under a zero-thickness ground plane is surface-aligned, not misplaced — so each axis gets
+        // an allowance of half the extent difference before its offset counts as divergence.
+        const vCenter = center(best.item.aabb);
+        const vSize2 = size(best.item.aabb);
+        const offsets = [
+            { axis: 'x', off: Math.abs(cCenter.x - vCenter.x), allow: Math.abs(cSize.x - vSize2.x) / 2 },
+            { axis: 'y', off: Math.abs(cCenter.y - vCenter.y), allow: Math.abs(cSize.y - vSize2.y) / 2 },
+            { axis: 'z', off: Math.abs(cCenter.z - vCenter.z), allow: Math.abs(cSize.z - vSize2.z) / 2 },
+        ];
+        const worstOffset = offsets.find((o) => o.off > Math.max(DIVERGENCE_OFFSET_M, o.allow + 0.05));
+        if (maxRatio > DIVERGENCE_RATIO || worstOffset) {
+            findings.push({
+                rule: 'collider-divergence',
+                severity: 'warn',
+                path: best.item.obj.path,
+                detail: `collider[${index}] diverges from this visual: extent ratio up to ${r2(maxRatio)}${worstOffset ? `, ${worstOffset.axis}-centers ${r2(worstOffset.off)} m apart` : ''}`,
+                measured: { maxRatio: r2(maxRatio), centerOffsetM: r2(best.dist) },
+                method: 'nearest-touching collider↔visual AABB comparison; offsets explained by extent asymmetry are allowed',
+                confidence: 'medium',
+            });
+        }
+    }
+    if (matchable.length > 0) {
+        for (const item of items) {
+            if (matchedVisuals.has(item.obj.path) || !item.obj.visible)
+                continue;
+            if (volume(item.aabb) < ORPHAN_VISUAL_MIN_VOLUME_M3)
+                continue;
+            findings.push({
+                rule: 'orphan-visual',
+                severity: 'info',
+                path: item.obj.path,
+                detail: 'sizeable visual with no collider near it — walk-through scenery, or a collider that was never added',
+                method: `no collider AABB matched; only visuals over ${ORPHAN_VISUAL_MIN_VOLUME_M3} m³ reported`,
+                confidence: 'low',
+            });
+        }
+    }
+}
+function transformRules(objects, findings) {
+    for (const obj of objects) {
+        if (obj.nonFinite) {
+            findings.push({
+                rule: 'degenerate',
+                severity: 'error',
+                path: obj.path,
+                detail: 'transform contains NaN/Infinity',
+                method: 'nonFinite flag from the in-page snapshot (JSON nulls the raw values in transit)',
+                confidence: 'high',
+            });
+            continue;
+        }
+        const s = obj.scale;
+        if ([s.x, s.y, s.z].some((c) => Math.abs(c) < DEGENERATE_SCALE)) {
+            findings.push({
+                rule: 'degenerate',
+                severity: 'error',
+                path: obj.path,
+                detail: `scale ≈ 0 (${s.x}, ${s.y}, ${s.z}) — the object renders as nothing`,
+                measured: { sx: s.x, sy: s.y, sz: s.z },
+                method: 'decomposed world scale below 1e-4',
+                confidence: 'high',
+            });
+        }
+        else if (s.x < 0 || s.y < 0 || s.z < 0) {
+            findings.push({
+                rule: 'mirrored',
+                severity: 'warn',
+                path: obj.path,
+                detail: `negative scale (${s.x}, ${s.y}, ${s.z}) — the mesh is mirrored, normals may face inward`,
+                measured: { sx: s.x, sy: s.y, sz: s.z },
+                method: 'negative matrix determinant carried on the decomposed scale',
+                confidence: 'high',
+            });
+        }
+        // LOD levels and toggled variants inside the character subtree are invisible by design,
+        // and toggling debug helpers (Line/Points) off is normal.
+        if (!obj.visible && !(0, exports.isCharacterSubtree)(obj.path) && !(0, exports.isHelperType)(obj.type)) {
+            findings.push({
+                rule: 'invisible',
+                severity: 'info',
+                path: obj.path,
+                detail: 'effectively invisible (visible:false on itself or an ancestor)',
+                method: 'visibility folded down the ancestor chain',
+                confidence: 'high',
+            });
+        }
+    }
+}
+function offGridRule(objects, findings) {
+    const groups = new Map();
+    for (const obj of objects) {
+        const parent = obj.path.includes('/') ? obj.path.slice(0, obj.path.lastIndexOf('/')) : '';
+        const list = groups.get(parent) ?? [];
+        list.push(obj);
+        groups.set(parent, list);
+    }
+    for (const [parent, siblings] of groups) {
+        if (siblings.length < OFF_GRID_MIN_SIBLINGS)
+            continue;
+        const yaws = siblings.map((s) => yawDeg(s.rotation));
+        // Coarsest grid the majority agrees on wins; a finer grid is a superset and adds no signal.
+        for (const grid of GRIDS_DEG) {
+            const onGrid = yaws.map((y) => {
+                const mod = y % grid;
+                return Math.min(mod, grid - mod) <= OFF_GRID_TOLERANCE_DEG;
+            });
+            const share = onGrid.filter(Boolean).length / siblings.length;
+            if (share < OFF_GRID_SHARE || onGrid.every(Boolean))
+                continue;
+            siblings.forEach((obj, i) => {
+                if (onGrid[i])
+                    return;
+                const yaw = yaws[i];
+                findings.push({
+                    rule: 'off-grid',
+                    severity: 'warn',
+                    path: obj.path,
+                    detail: `yaw ${r2(yaw)}° while ${Math.round(share * 100)}% of its siblings${parent ? ` under ${parent}` : ''} sit on a ${grid}° grid`,
+                    measured: { yawDeg: r2(yaw), gridDeg: grid },
+                    method: 'yaw vs the modal sibling grid; fires only when siblings agree on a grid',
+                    confidence: 'medium',
+                });
+            });
+            break;
+        }
+    }
+}
+function outOfBoundsRule(items, findings) {
+    if (items.length < 3)
+        return;
+    const centers = items.map((i) => center(i.aabb));
+    const median = (values) => {
+        const sorted = [...values].sort((a, b) => a - b);
+        return sorted[Math.floor(sorted.length / 2)];
+    };
+    const mid = { x: median(centers.map((c) => c.x)), y: median(centers.map((c) => c.y)), z: median(centers.map((c) => c.z)) };
+    const dists = centers.map((c) => Math.hypot(c.x - mid.x, c.y - mid.y, c.z - mid.z)).sort((a, b) => a - b);
+    // floor((n-1)·0.9) keeps the top decile — including the max itself — OUT of the bulk radius,
+    // otherwise a single 1e6 stray inflates the radius and can never be flagged.
+    const bulkRadius = dists[Math.floor((dists.length - 1) * 0.9)];
+    const threshold = Math.max(OUT_OF_BOUNDS_FACTOR * bulkRadius, OUT_OF_BOUNDS_MIN_M);
+    items.forEach((item, i) => {
+        const d = Math.hypot(centers[i].x - mid.x, centers[i].y - mid.y, centers[i].z - mid.z);
+        if (d <= threshold)
+            return;
+        findings.push({
+            rule: 'out-of-bounds',
+            severity: 'error',
+            path: item.obj.path,
+            detail: `${r2(d)} m from the bulk of the scene (bulk radius ${r2(bulkRadius)} m) — stray coordinate?`,
+            measured: { distanceM: r2(d), bulkRadiusM: r2(bulkRadius) },
+            method: `center beyond max(${OUT_OF_BOUNDS_FACTOR}× the 90th-percentile bulk radius, ${OUT_OF_BOUNDS_MIN_M} m) from the median center`,
+            confidence: 'high',
+        });
+    });
+}
+const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 };
+function analyzeWorld(snapshot) {
+    const findings = [];
+    const notes = [];
+    if (snapshot.truncated) {
+        notes.push(`roster truncated: ${snapshot.truncated.emitted} of ${snapshot.truncated.total} objects in the payload — findings only cover what was emitted`);
+    }
+    if (snapshot.sources.colliders === 'unsupported') {
+        notes.push("collider checks skipped — this world's humanoid-character predates describeColliders (< 0.2.13)");
+    }
+    else if (snapshot.sources.colliders === 'absent') {
+        notes.push('collider checks skipped — the world passed no body to world.ready()');
+    }
+    const characterCount = snapshot.objects.filter((o) => (0, exports.isCharacterSubtree)(o.path)).length;
+    if (characterCount > 0) {
+        notes.push(`character subtree excluded from placement rules (${characterCount} objects under */character-lod/*)`);
+    }
+    const layoutObjects = snapshot.objects.filter((o) => !(0, exports.isCharacterSubtree)(o.path) && !(0, exports.isHelperType)(o.type));
+    const items = layoutObjects
+        .filter((o) => o.aabb !== null && !o.nonFinite)
+        .map((o) => ({ obj: o, aabb: o.aabb }));
+    const colliders = snapshot.sources.colliders === 'ok' ? snapshot.colliders : [];
+    transformRules(snapshot.objects, findings);
+    supportRules(items, colliders, findings);
+    intersectionRule(items, findings);
+    if (snapshot.sources.colliders === 'ok')
+        colliderRules(items, colliders, findings);
+    offGridRule(layoutObjects, findings);
+    outOfBoundsRule(items, findings);
+    reachabilityRule(items, colliders, snapshot.spawn, findings);
+    collapseCompositeInternals(findings);
+    collapseUniformOverlaps(findings);
+    sortFindings(findings);
+    return { findings, notes };
+}
+// A composite model's internals (table = top + legs + skirt, one parent group) overlap by
+// construction — each pair is already demoted to info, but a furniture-heavy world states the same
+// "this is one glued model" fact dozens of times. ≥RUN_COLLAPSE_MIN internal-overlap infos under one
+// parent collapse to a single per-model summary; the deepest penetration is preserved.
+function collapseCompositeInternals(findings) {
+    const groups = new Map();
+    for (const f of findings) {
+        if (f.rule !== 'intersecting' || f.severity !== 'info' || !f.detail.includes('(composite model internals)'))
+            continue;
+        const parent = f.path.split('/').slice(0, -1).join('/');
+        const list = groups.get(parent) ?? [];
+        list.push(f);
+        groups.set(parent, list);
+    }
+    for (const [parent, group] of groups.entries()) {
+        if (group.length < RUN_COLLAPSE_MIN)
+            continue;
+        const deepest = Math.max(...group.map((f) => f.measured?.penetrationM ?? f.measured?.dyM ?? 0));
+        for (const f of group)
+            findings.splice(findings.indexOf(f), 1);
+        findings.push({
+            rule: 'intersecting',
+            severity: 'info',
+            path: parent === '' ? group[0].path : parent,
+            detail: `${group.length} internal overlaps within ${parent === '' ? 'the scene root' : parent} (composite model) — ` +
+                `deepest ${r2(deepest)} m; internals of one glued model, not layout`,
+            measured: { pairs: group.length, penetrationMaxM: r2(deepest) },
+            method: 'per-parent collapse of composite-model-internal overlaps',
+            confidence: 'low',
+        });
+    }
+}
+// Exported so callers merging extra findings (the zone checks) can restore the canonical order.
+function sortFindings(findings) {
+    return findings.sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+        a.rule.localeCompare(b.rule) ||
+        a.path.localeCompare(b.path));
+}
+// Equal-depth overlaps in bulk are the signature of corner joints and repeated trim — walls
+// deliberately overlapping at their ends share one thickness, so their depths match. Three or
+// more warn-level overlaps within a 0.02 m bucket collapse to a single info summary; a lone odd
+// overlap keeps its warn.
+function collapseUniformOverlaps(findings) {
+    const buckets = new Map();
+    for (const f of findings) {
+        if (f.rule !== 'intersecting' || f.severity !== 'warn' || f.measured?.penetrationM === undefined)
+            continue;
+        const bucket = Math.round(f.measured.penetrationM / 0.02);
+        const list = buckets.get(bucket) ?? [];
+        list.push(f);
+        buckets.set(bucket, list);
+    }
+    for (const group of buckets.values()) {
+        if (group.length < 3)
+            continue;
+        const depth = group[0].measured.penetrationM ?? 0;
+        const paths = new Set(group.flatMap((f) => [f.path]));
+        for (const f of group)
+            findings.splice(findings.indexOf(f), 1);
+        findings.push({
+            rule: 'intersecting',
+            severity: 'info',
+            path: group[0].path,
+            detail: `${group.length} overlaps of uniform ~${depth} m depth across the scene (e.g. ${[...paths].slice(0, 3).join(', ')}) — equal depths read as corner joints / repeated trim, likely intentional`,
+            measured: { pairs: group.length, penetrationM: depth },
+            method: 'uniform-depth grouping of separating-axis overlaps',
+            confidence: 'low',
+        });
+    }
+}
+// ---- Reachability: can the player actually GET to what the world puts up there? ----------------
+//
+// The gap this closes: a game's objective sat on a 0.42 m dais against the character's 0.35 m step
+// height. It was physically unreachable, and NOTHING said so — build, validate, inspect, screenshot
+// and the sub-path load were all green, because every one of them checks that the world renders,
+// not that it can be played.
+//
+// SCOPE, deliberately narrow. This is a VERTICAL step-up check over stacked surfaces, not a
+// navmesh. It models: standing on a surface, walking to an edge, stepping up ≤ step height, and
+// dropping down any distance. It does NOT model jumping, ramps/terrain slopes, moving platforms,
+// teleports, ladders, or horizontal blockage — so it reports `warn`, never `error`, and every
+// finding names the measured rise against the threshold so a human can judge it. A checker that
+// confidently invents unreachability would get trusted and send someone hunting the wrong bug.
+const REACH_M = 0.5; // how far past a footprint edge the character can stand to step up
+/** Surfaces whose footprints are within arm's reach horizontally — i.e. you can stand at the edge. */
+const xzAdjacent = (a, b) => a.min.x - REACH_M < b.max.x &&
+    a.max.x + REACH_M > b.min.x &&
+    a.min.z - REACH_M < b.max.z &&
+    a.max.z + REACH_M > b.min.z;
+function reachabilityRule(items, colliders, spawn, findings) {
+    const visible = items.filter((i) => i.obj.visible);
+    if (visible.length === 0)
+        return;
+    const platforms = [
+        ...visible.map((i) => ({ top: i.aabb.max.y, label: i.obj.path, aabb: i.aabb })),
+        ...colliders
+            .map((c, index) => ({ index, aabb: colliderAabb(c) }))
+            .filter((x) => x.aabb !== null)
+            .map(({ index, aabb }) => ({ top: aabb.max.y, label: `collider[${index}]`, aabb })),
+    ];
+    if (platforms.length === 0)
+        return;
+    // Standing height: the spawn's own feet if the world declared one, else the lowest surface you
+    // could stand ON — the lowest platform TOP, not the lowest AABB bottom. Using the bottom reads a
+    // thick floor slab (y -2..0) as a 2 m wall and flags everything resting on it as unreachable.
+    const groundY = spawn ? spawn.y : Math.min(...platforms.map((p) => p.top));
+    // Flood-fill upward from the ground. A platform joins the reachable set when it is within one
+    // step of something already reachable AND close enough horizontally to walk to. Dropping DOWN is
+    // free, so a lower adjacent platform is always reachable from a higher one.
+    const reachable = new Set();
+    platforms.forEach((p, i) => {
+        if (p.top - groundY <= exports.STEP_HEIGHT_M)
+            reachable.add(i);
+    });
+    for (let changed = true; changed;) {
+        changed = false;
+        for (let i = 0; i < platforms.length; i += 1) {
+            if (reachable.has(i))
+                continue;
+            for (const j of reachable) {
+                const rise = platforms[i].top - platforms[j].top;
+                if (rise <= exports.STEP_HEIGHT_M && xzAdjacent(platforms[i].aabb, platforms[j].aabb)) {
+                    reachable.add(i);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    // Only report a surface that the world PUT SOMETHING ON. An unreachable bare ledge is scenery;
+    // an unreachable surface carrying an object is a thing the player was meant to get to.
+    for (let i = 0; i < platforms.length; i += 1) {
+        if (reachable.has(i))
+            continue;
+        const platform = platforms[i];
+        const carried = visible.filter((it) => it.obj.path !== platform.label &&
+            xzOverlaps(it.aabb, platform.aabb) &&
+            Math.abs(it.aabb.min.y - platform.top) <= exports.STEP_HEIGHT_M &&
+            it.aabb.max.y > platform.top);
+        if (carried.length === 0)
+            continue;
+        // The smallest step that would make it reachable — the number to act on.
+        let bestRise = platform.top - groundY;
+        for (const j of reachable) {
+            if (!xzAdjacent(platform.aabb, platforms[j].aabb))
+                continue;
+            bestRise = Math.min(bestRise, platform.top - platforms[j].top);
+        }
+        findings.push({
+            rule: 'unreachable',
+            severity: 'warn',
+            path: platform.label,
+            detail: `unreachable on foot: a ${r2(bestRise)} m step up, against the character's ${exports.STEP_HEIGHT_M} m step height` +
+                ` — and it carries ${carried.length === 1 ? carried[0].obj.path : `${carried.length} objects`}.` +
+                ` Lower it to ${r2(exports.STEP_HEIGHT_M)} m or add an intermediate step/ramp.`,
+            measured: { riseM: r2(bestRise), stepHeightM: exports.STEP_HEIGHT_M, carried: carried.length },
+            method: `vertical step flood-fill from ${spawn ? 'the declared spawn' : 'the lowest surface'} ` +
+                `(y=${r2(groundY)}); reach ${REACH_M} m horizontally. Ignores jumps, ramps and teleports`,
+            confidence: 'medium',
+        });
+    }
+}
+//# sourceMappingURL=analyze.js.map