@helix3/helix-cli 0.1.7-helix3.45 → 0.1.8-helix3.47

package/dist/world/diff.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffWorldSnapshots = diffWorldSnapshots;
+exports.formatWorldDiff = formatWorldDiff;
+const analyze_1 = require("./analyze");
+const MOVE_EPSILON_M = 0.01;
+const r3 = (n) => Math.round(n * 1000) / 1000;
+const findingKey = (f) => `${f.rule}|${f.path}`;
+function diffWorldSnapshots(before, after) {
+    const beforeByPath = new Map(before.objects.map((o) => [o.path, o]));
+    const afterByPath = new Map(after.objects.map((o) => [o.path, o]));
+    const added = [...afterByPath.keys()].filter((p) => !beforeByPath.has(p));
+    const removed = [...beforeByPath.keys()].filter((p) => !afterByPath.has(p));
+    const moved = [];
+    for (const [path, a] of beforeByPath) {
+        const b = afterByPath.get(path);
+        if (!b)
+            continue;
+        const delta = { x: r3(b.position.x - a.position.x), y: r3(b.position.y - a.position.y), z: r3(b.position.z - a.position.z) };
+        const distance = Math.hypot(delta.x, delta.y, delta.z);
+        if (distance <= MOVE_EPSILON_M)
+            continue;
+        moved.push({ path, from: a.position, to: b.position, delta, distance: r3(distance) });
+    }
+    moved.sort((a, b) => b.distance - a.distance);
+    const beforeFindings = new Map((0, analyze_1.analyzeWorld)(before).findings.map((f) => [findingKey(f), f]));
+    const afterFindings = new Map((0, analyze_1.analyzeWorld)(after).findings.map((f) => [findingKey(f), f]));
+    const findingsAppeared = [...afterFindings.entries()].filter(([k]) => !beforeFindings.has(k)).map(([, f]) => f);
+    const findingsCleared = [...beforeFindings.entries()].filter(([k]) => !afterFindings.has(k)).map(([, f]) => f);
+    return { added, removed, moved, findingsAppeared, findingsCleared };
+}
+function formatWorldDiff(diff) {
+    const lines = [];
+    lines.push(`world diff — ${diff.added.length} added, ${diff.removed.length} removed, ${diff.moved.length} moved, ` +
+        `${diff.findingsAppeared.length} findings appeared, ${diff.findingsCleared.length} cleared`);
+    if (diff.added.length) {
+        lines.push('', 'added:');
+        lines.push(...diff.added.map((p) => `  + ${p}`));
+    }
+    if (diff.removed.length) {
+        lines.push('', 'removed:');
+        lines.push(...diff.removed.map((p) => `  - ${p}`));
+    }
+    if (diff.moved.length) {
+        lines.push('', 'moved:');
+        lines.push(...diff.moved.map((m) => `  ~ ${m.path}: Δ(${m.delta.x}, ${m.delta.y}, ${m.delta.z}) — ${m.distance} m`));
+    }
+    if (diff.findingsAppeared.length) {
+        lines.push('', 'findings appeared:');
+        lines.push(...diff.findingsAppeared.map((f) => `  ! [${f.severity}] ${f.rule} ${f.path} — ${f.detail}`));
+    }
+    if (diff.findingsCleared.length) {
+        lines.push('', 'findings cleared:');
+        lines.push(...diff.findingsCleared.map((f) => `  ✓ [${f.severity}] ${f.rule} ${f.path}`));
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=diff.js.map

package/dist/world/diff.js.map

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

package/dist/world/focus.d.ts

@@ -0,0 +1,11 @@
+import type { SnapshotObject, WorldSnapshot } from './snapshotTypes';
+import { type AnalysisResult } from './analyze';
+export interface FocusQuery {
+    /** Case-insensitive substring of the object path (for named/imported objects). */
+    path?: string | undefined;
+    /** World-space point — matches objects whose AABB is within `radius` of it (0 when inside). */
+    near?: [number, number, number] | undefined;
+    radius?: number | undefined;
+}
+export declare function resolveFocus(snapshot: WorldSnapshot, query: FocusQuery): SnapshotObject[];
+export declare function formatWorldFocus(snapshot: WorldSnapshot, analysis: AnalysisResult, query: FocusQuery): string;

package/dist/world/focus.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFocus = resolveFocus;
+exports.formatWorldFocus = formatWorldFocus;
+const analyze_1 = require("./analyze");
+const DEFAULT_NEAR_RADIUS_M = 2;
+const r2 = (n) => Math.round(n * 100) / 100;
+/** Distance from a point to an AABB — 0 when the point is inside. */
+function pointToAabb(p, b) {
+    const dx = Math.max(b.min.x - p.x, 0, p.x - b.max.x);
+    const dy = Math.max(b.min.y - p.y, 0, p.y - b.max.y);
+    const dz = Math.max(b.min.z - p.z, 0, p.z - b.max.z);
+    return Math.hypot(dx, dy, dz);
+}
+function resolveFocus(snapshot, query) {
+    const candidates = snapshot.objects.filter((o) => o.aabb !== null);
+    if (query.path !== undefined) {
+        const needle = query.path.toLowerCase();
+        return candidates.filter((o) => o.path.toLowerCase().includes(needle));
+    }
+    if (query.near !== undefined) {
+        const p = { x: query.near[0], y: query.near[1], z: query.near[2] };
+        const radius = query.radius ?? DEFAULT_NEAR_RADIUS_M;
+        return candidates
+            .map((o) => ({ o, d: pointToAabb(p, o.aabb) }))
+            .filter(({ d }) => d <= radius)
+            .sort((a, b) => a.d - b.d)
+            .map(({ o }) => o);
+    }
+    return [];
+}
+// A finding involves a focused object when it is the subject OR its detail names the path as a
+// whole token — plain substring would make Mesh#1 swallow Mesh#10.
+function findingMentions(pathsSet, subject, detail) {
+    if (pathsSet.has(subject))
+        return true;
+    for (const path of pathsSet) {
+        const esc = path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        if (new RegExp(`(?<!\\w)${esc}(?!\\w)`).test(detail))
+            return true;
+    }
+    return false;
+}
+function formatWorldFocus(snapshot, analysis, query) {
+    const focused = resolveFocus(snapshot, query);
+    const lines = [];
+    const queryLabel = query.path !== undefined ? `path ~ "${query.path}"` : `near (${(query.near ?? []).join(', ')}) r=${query.radius ?? DEFAULT_NEAR_RADIUS_M}`;
+    if (focused.length === 0) {
+        lines.push(`focus ${queryLabel} — no objects matched.`);
+        // The agent's coordinate was off, or the object never made it into the scene — the three
+        // nearest objects answer both ("it landed over THERE" vs "it does not exist").
+        if (query.near !== undefined) {
+            const p = { x: query.near[0], y: query.near[1], z: query.near[2] };
+            const nearest = snapshot.objects
+                .filter((o) => o.aabb !== null)
+                .map((o) => ({ o, d: pointToAabb(p, o.aabb) }))
+                .sort((a, b) => a.d - b.d)
+                .slice(0, 3);
+            if (nearest.length) {
+                lines.push('nearest objects:');
+                for (const { o, d } of nearest)
+                    lines.push(`  ${o.path} — ${r2(d)} m away @ (${o.position.x}, ${o.position.y}, ${o.position.z})`);
+            }
+        }
+        return lines.join('\n');
+    }
+    lines.push(`focus ${queryLabel} — ${focused.length} object${focused.length === 1 ? '' : 's'}:`);
+    const colliderBoxes = snapshot.colliders
+        .map((c, index) => ({ c, index, aabb: (0, analyze_1.colliderAabb)(c) }))
+        .filter((x) => x.aabb !== null);
+    for (const o of focused) {
+        const b = o.aabb;
+        const size = { x: r2(b.max.x - b.min.x), y: r2(b.max.y - b.min.y), z: r2(b.max.z - b.min.z) };
+        lines.push(`  ${o.path} (${o.geometry ?? o.type}${o.color ? ` ${o.color}` : ''}${o.visible ? '' : ', INVISIBLE'})`);
+        lines.push(`      position (${o.position.x}, ${o.position.y}, ${o.position.z}) · size ${size.x}×${size.y}×${size.z} · ${o.triangles} tris`);
+        lines.push(`      aabb x[${r2(b.min.x)}..${r2(b.max.x)}] y[${r2(b.min.y)}..${r2(b.max.y)}] z[${r2(b.min.z)}..${r2(b.max.z)}]`);
+        // Touching colliders (gap ≤ 0.1 on every axis) — "does my object have collision" at a glance.
+        const touching = colliderBoxes.filter(({ aabb }) => {
+            const gx = Math.max(aabb.min.x - b.max.x, b.min.x - aabb.max.x, 0);
+            const gy = Math.max(aabb.min.y - b.max.y, b.min.y - aabb.max.y, 0);
+            const gz = Math.max(aabb.min.z - b.max.z, b.min.z - aabb.max.z, 0);
+            return gx <= 0.1 && gy <= 0.1 && gz <= 0.1;
+        });
+        lines.push(touching.length
+            ? `      colliders touching: ${touching.map(({ c, index }) => `[${index}] ${c.shape}`).join(', ')}`
+            : `      colliders touching: none${snapshot.sources.colliders === 'ok' ? ' — walk-through unless intended' : ` (collider source: ${snapshot.sources.colliders})`}`);
+    }
+    const pathsSet = new Set(focused.map((o) => o.path));
+    const involved = analysis.findings.filter((f) => findingMentions(pathsSet, f.path, f.detail));
+    lines.push('');
+    lines.push(`findings involving the focused object${focused.length === 1 ? '' : 's'} (world total: ${analysis.findings.length}):`);
+    if (involved.length === 0)
+        lines.push('  (none)');
+    else
+        for (const f of involved)
+            lines.push(`  [${f.severity}] ${f.rule} — ${f.detail}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=focus.js.map

package/dist/world/focus.js.map

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

package/dist/world/format.d.ts

@@ -0,0 +1,6 @@
+import type { WorldSnapshot } from './snapshotTypes';
+import type { AnalysisResult } from './analyze';
+import type { ZoneReport } from './zones';
+export type ReportSection = 'anomalies' | 'roster' | 'colliders' | 'zones';
+export declare const DEFAULT_REPORT: ReportSection[];
+export declare function formatWorldInspection(snapshot: WorldSnapshot, analysis: AnalysisResult, report?: ReportSection[], zones?: ZoneReport[] | null): string;

package/dist/world/format.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REPORT = void 0;
+exports.formatWorldInspection = formatWorldInspection;
+exports.DEFAULT_REPORT = ['anomalies'];
+// A genuinely broken world can carry hundreds of findings of one kind; the render caps each rule
+// at the worst N (the list is severity-sorted) with an explicit overflow line — same never-silent
+// principle as the roster truncation. The json output always carries the full list.
+const MAX_FINDINGS_PER_RULE = 10;
+const r1 = (n) => Math.round(n * 10) / 10;
+function formatFinding(f) {
+    const measured = f.measured
+        ? ` {${Object.entries(f.measured)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join(', ')}}`
+        : '';
+    return `  [${f.severity}] ${f.rule} ${f.path} — ${f.detail}${measured}\n         method: ${f.method}; confidence: ${f.confidence}`;
+}
+function formatRoster(snapshot) {
+    const groups = new Map();
+    for (const obj of snapshot.objects) {
+        const s = obj.aabb
+            ? `${r1(obj.aabb.max.x - obj.aabb.min.x)}×${r1(obj.aabb.max.y - obj.aabb.min.y)}×${r1(obj.aabb.max.z - obj.aabb.min.z)}`
+            : 'no-aabb';
+        const key = `${obj.type}|${obj.geometry ?? '-'}|${obj.triangles}|${s}|${obj.color ?? '-'}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.count++;
+            if (obj.aabb) {
+                existing.min.x = Math.min(existing.min.x, obj.aabb.min.x);
+                existing.min.z = Math.min(existing.min.z, obj.aabb.min.z);
+                existing.max.x = Math.max(existing.max.x, obj.aabb.max.x);
+                existing.max.z = Math.max(existing.max.z, obj.aabb.max.z);
+            }
+        }
+        else {
+            groups.set(key, {
+                key,
+                label: `${obj.geometry ?? obj.type} tris=${obj.triangles} size=${s}${obj.color ? ` ${obj.color}` : ''}`,
+                count: 1,
+                min: { x: obj.aabb?.min.x ?? 0, z: obj.aabb?.min.z ?? 0 },
+                max: { x: obj.aabb?.max.x ?? 0, z: obj.aabb?.max.z ?? 0 },
+                firstPath: obj.path,
+            });
+        }
+    }
+    return [...groups.values()]
+        .sort((a, b) => b.count - a.count)
+        .map((g) => `  ${String(g.count).padStart(3)}× ${g.label} — e.g. ${g.firstPath}` +
+        (g.count > 1 ? ` (spread x[${r1(g.min.x)}..${r1(g.max.x)}] z[${r1(g.min.z)}..${r1(g.max.z)}])` : ''));
+}
+function formatColliders(snapshot) {
+    if (snapshot.sources.colliders !== 'ok')
+        return [`  (skipped — sources.colliders: ${snapshot.sources.colliders})`];
+    if (snapshot.colliders.length === 0)
+        return ['  (none)'];
+    // Ordinal labels — Rapier handles are opaque f64 bit-packs that print as denormals.
+    return snapshot.colliders.map((c, i) => {
+        const extent = c.halfExtents
+            ? `he ${c.halfExtents.x}×${c.halfExtents.y}×${c.halfExtents.z}`
+            : typeof c.radius === 'number'
+                ? `r ${c.radius}${typeof c.halfHeight === 'number' ? ` hh ${c.halfHeight}` : ''}`
+                : '';
+        return `  [${i}] ${c.shape} ${extent} @ (${c.position.x}, ${c.position.y}, ${c.position.z})`;
+    });
+}
+function formatWorldInspection(snapshot, analysis, report = exports.DEFAULT_REPORT, zones) {
+    const lines = [];
+    const spawn = snapshot.spawn ? `(${snapshot.spawn.x}, ${snapshot.spawn.y}, ${snapshot.spawn.z})` : '(not provided)';
+    lines.push(`world inspect — ${snapshot.objects.length} objects, ${snapshot.colliders.length} colliders (source: ${snapshot.sources.colliders}), spawn ${spawn}`);
+    for (const note of analysis.notes)
+        lines.push(`note: ${note}`);
+    if (report.includes('anomalies')) {
+        const counts = { error: 0, warn: 0, info: 0 };
+        for (const f of analysis.findings)
+            counts[f.severity]++;
+        lines.push('');
+        lines.push(`anomalies (${counts.error} error, ${counts.warn} warn, ${counts.info} info):`);
+        if (analysis.findings.length === 0)
+            lines.push('  (none — every placement check passed)');
+        else {
+            const shownPerRule = new Map();
+            const overflow = new Map();
+            for (const f of analysis.findings) {
+                const shown = shownPerRule.get(f.rule) ?? 0;
+                if (shown < MAX_FINDINGS_PER_RULE) {
+                    shownPerRule.set(f.rule, shown + 1);
+                    lines.push(formatFinding(f));
+                }
+                else {
+                    overflow.set(f.rule, (overflow.get(f.rule) ?? 0) + 1);
+                }
+            }
+            for (const [rule, n] of overflow) {
+                lines.push(`  … and ${n} more ${rule} finding${n === 1 ? '' : 's'} — the worst ${MAX_FINDINGS_PER_RULE} are shown (severity-sorted); the json output carries the full list`);
+            }
+        }
+    }
+    if (report.includes('roster')) {
+        lines.push('');
+        lines.push('roster (grouped):');
+        lines.push(...formatRoster(snapshot));
+    }
+    if (report.includes('colliders')) {
+        lines.push('');
+        lines.push('colliders:');
+        lines.push(...formatColliders(snapshot));
+    }
+    if (report.includes('zones')) {
+        lines.push('');
+        lines.push('zones (from multiplayer.json):');
+        if (!zones || zones.length === 0)
+            lines.push('  (none declared, or no multiplayer.json beside the bundle)');
+        else
+            for (const z of zones) {
+                lines.push(`  ${z.id}: ${z.extent}`);
+                lines.push(`      rest surfaces: ${z.restSurfaces.length ? z.restSurfaces.slice(0, 6).join(', ') : '(none — mid-air entry only)'}`);
+                lines.push(`      touches: ${z.touches.length ? z.touches.slice(0, 6).join(', ') : '(no geometry)'}`);
+            }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/world/format.js.map

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

package/dist/world/readWorldMetrics.d.ts

@@ -0,0 +1,10 @@
+export interface WorldMetricsTable {
+    capsule: Record<string, number>;
+    traversal: Record<string, number>;
+    movement: Record<string, number>;
+    derived: Record<string, number>;
+}
+/** Null when the installed system predates WORLD_METRICS (< 0.2.13) — callers degrade with a message. */
+export declare function readWorldMetrics(worldDir: string): Promise<WorldMetricsTable | null>;
+export declare function renderWorldMetrics(metrics: WorldMetricsTable): string;
+export declare const METRICS_UNSUPPORTED_MESSAGE: string;

package/dist/world/readWorldMetrics.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METRICS_UNSUPPORTED_MESSAGE = void 0;
+exports.readWorldMetrics = readWorldMetrics;
+exports.renderWorldMetrics = renderWorldMetrics;
+// Reads WORLD_METRICS from a world's OWN installed humanoid-character system (the readAxisTable
+// pattern) — version-correct per world, so the table always matches the system the world actually
+// runs. CLI-only: the engine tool reads the workspace package directly.
+const node_url_1 = require("node:url");
+const esm_1 = require("../character/esm");
+const worldRuntime_1 = require("../gesture/worldRuntime");
+/** Null when the installed system predates WORLD_METRICS (< 0.2.13) — callers degrade with a message. */
+async function readWorldMetrics(worldDir) {
+    const entry = (0, worldRuntime_1.systemEntry)(worldDir);
+    const system = await (0, esm_1.importEsm)((0, node_url_1.pathToFileURL)(entry).href);
+    const metrics = system.WORLD_METRICS;
+    return metrics ?? null;
+}
+function renderWorldMetrics(metrics) {
+    const lines = ['world metrics — system DEFAULTS (worlds may override via config):'];
+    for (const [group, values] of Object.entries(metrics)) {
+        lines.push(`  ${group}:`);
+        for (const [k, v] of Object.entries(values))
+            lines.push(`    ${k}: ${v}`);
+    }
+    return lines.join('\n');
+}
+exports.METRICS_UNSUPPORTED_MESSAGE = 'the installed humanoid-character does not export WORLD_METRICS — it predates the table (added in 0.2.13).\n' +
+    '  Any existing ^0.2 pin already allows it — rerun the install and rebuild:\n' +
+    '  MCP: install_world_packages · CLI: helix install (via npx: `npx @hypersoniclabs/helix-cli install` — bare `helix` is an unrelated npm package).';
+//# sourceMappingURL=readWorldMetrics.js.map

package/dist/world/readWorldMetrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readWorldMetrics.js","sourceRoot":"","sources":["../../src/world/readWorldMetrics.ts"],"names":[],"mappings":";;;AAeA,4CAKC;AAED,gDAOC;AA7BD,gGAAgG;AAChG,kGAAkG;AAClG,wEAAwE;AACxE,uCAAyC;AACzC,0CAA6C;AAC7C,0DAAsD;AAStD,yGAAyG;AAClG,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IACrD,MAAM,KAAK,GAAG,IAAA,0BAAW,EAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,MAAM,IAAA,eAAS,EAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,aAA8C,CAAC;IACtE,OAAO,OAAO,IAAI,IAAI,CAAC;AACzB,CAAC;AAED,SAAgB,kBAAkB,CAAC,OAA0B;IAC3D,MAAM,KAAK,GAAa,CAAC,mEAAmE,CAAC,CAAC;IAC9F,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC;QAC1B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAEY,QAAA,2BAA2B,GACtC,6GAA6G;IAC7G,8EAA8E;IAC9E,mJAAmJ,CAAC"}

package/dist/world/snapshotTypes.d.ts

@@ -0,0 +1,59 @@
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+export interface ColliderInfo {
+    handle: number;
+    /** Lowercased Rapier shape name: 'cuboid', 'trimesh', 'ball', 'capsule', … */
+    shape: string;
+    halfExtents?: Vec3;
+    radius?: number;
+    halfHeight?: number;
+    position: Vec3;
+    rotation: Quat;
+}
+export interface SnapshotObject {
+    path: string;
+    type: string;
+    geometry: string | null;
+    position: Vec3;
+    rotation: Quat;
+    scale: Vec3;
+    aabb: {
+        min: Vec3;
+        max: Vec3;
+    } | null;
+    obb: {
+        center: Vec3;
+        half: Vec3;
+    } | null;
+    visible: boolean;
+    triangles: number;
+    color: string | null;
+    nonFinite?: true;
+}
+export type ColliderSource = 'ok' | 'unsupported' | 'absent';
+export interface WorldSnapshot {
+    snapshotVersion: 1;
+    spawn: Vec3 | null;
+    objects: SnapshotObject[];
+    colliders: ColliderInfo[];
+    sources: {
+        scene: true;
+        colliders: ColliderSource;
+    };
+    truncated?: {
+        emitted: number;
+        total: number;
+    };
+}
+export interface SnapshotOptions {
+    maxObjects?: number;
+}

package/dist/world/snapshotTypes.js

@@ -0,0 +1,8 @@
+"use strict";
+// The world-snapshot contract — the JSON a world's in-page inspect helper serializes.
+// PORTED from helix-web-engine-new/systems/engine-core/src/inspect/WorldInspect.ts (the type
+// declarations only) — the source of truth for the snapshot contract. SYNC OBLIGATION: change the
+// shape there first (it is what worlds actually emit, versioned via snapshotVersion), then mirror
+// here; do not diverge.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=snapshotTypes.js.map

package/dist/world/snapshotTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotTypes.js","sourceRoot":"","sources":["../../src/world/snapshotTypes.ts"],"names":[],"mappings":";AAAA,sFAAsF;AACtF,6FAA6F;AAC7F,kGAAkG;AAClG,kGAAkG;AAClG,wBAAwB"}

package/dist/world/snapshotWorld.d.ts

@@ -0,0 +1,16 @@
+import { type BrowserKey, type HelperTimeoutState } from '../browser/launch';
+import type { WorldSnapshot } from './snapshotTypes';
+export declare function composeInspectTimeoutDiagnosis(state: HelperTimeoutState, errors: string[]): string;
+export type SnapshotWorldOptions = {
+    directory: string;
+    timeoutMs?: number | undefined;
+    /** Frames/assets settle time between helper-ready and the snapshot — determinism lever. */
+    settleMs?: number | undefined;
+    maxObjects?: number | undefined;
+    /** Diagnostic override: launch only this candidate, no fallback (default: try the whole chain). */
+    browser?: BrowserKey | undefined;
+    /** URL-prefix → dir fallbacks (e.g. a shared character-asset tree at /assets, /basis). */
+    fallbackMounts?: Record<string, string> | undefined;
+    onProgress?: ((message: string) => void) | undefined;
+};
+export declare function snapshotWorld(opts: SnapshotWorldOptions): Promise<WorldSnapshot>;

package/dist/world/snapshotWorld.js

@@ -0,0 +1,120 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeInspectTimeoutDiagnosis = composeInspectTimeoutDiagnosis;
+exports.snapshotWorld = snapshotWorld;
+// Headless snapshot transport for `helix world inspect`: serves the built bundle, drives the
+// in-page inspect helper (window.__helixInspect) via Playwright, and returns the serialized
+// WorldSnapshot. The helper ships in @helix/engine-core/inspect — this module only speaks its
+// window protocol and never imports the engine.
+// PORTED from helix-web-engine-new/tools/world-inspect/src/snapshotWorld.ts, rewired to the CLI's
+// shared browser harness (full playwright with the bundled-Chromium candidate — the engine tool
+// deliberately runs playwright-core with system channels only). The analysis mirror is strict;
+// this transport divergence is expected and documented on both sides.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const launch_1 = require("../browser/launch");
+const staticServe_1 = require("../screenshot/staticServe");
+const MAX_DIAGNOSTIC_LINES = 6;
+const DIAGNOSTIC_LINE_MAX_CHARS = 300;
+const DEFAULT_SETTLE_MS = 750;
+function composeInspectTimeoutDiagnosis(state, errors) {
+    return (0, launch_1.composeTimeoutDiagnosisWith)(state, errors, {
+        absent: 'This world does not integrate @helix/engine-core/inspect — add the "engine-core" system pin to helix.json ' +
+            "alongside humanoid-character, run helix install, wire world.ready({ scene, body, spawn }) at the end of " +
+            'boot (see the MCP world-inspect doc), and rebuild.',
+        present: 'The world loaded the inspect helper but its boot never completed — this looks like a load/boot failure, ' +
+            'not a missing integration. Check that the world runs standalone (missing character assets are the common cause).',
+    });
+}
+async function snapshotWorld(opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const timeoutMs = opts.timeoutMs ?? 60000;
+    const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(opts.directory, 'index.html'))) {
+        throw new Error(`${opts.directory} is not a built world dir (no index.html) — point at the bundle build output (usually <world>/dist).`);
+    }
+    const playwright = await Promise.resolve().then(() => __importStar(require('playwright')));
+    const server = await (0, staticServe_1.startStaticServer)(opts.directory, opts.fallbackMounts ?? {});
+    let browser;
+    try {
+        const attempts = [];
+        for (const candidate of (0, launch_1.selectBrowserCandidates)(opts.browser)) {
+            try {
+                browser = await playwright.chromium.launch(candidate.launchOptions);
+                onProgress(`using ${candidate.label}`);
+                break;
+            }
+            catch (err) {
+                attempts.push({ key: candidate.key, label: candidate.label, message: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        if (!browser)
+            throw new Error((0, launch_1.composeLaunchFailure)(attempts));
+        const page = await browser.newPage({ viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 });
+        // Ring buffer of the last few load-time page errors — surfaced in the timeout diagnosis below.
+        const pageErrors = [];
+        const recordPageError = (line) => {
+            const truncated = line.length > DIAGNOSTIC_LINE_MAX_CHARS ? `${line.slice(0, DIAGNOSTIC_LINE_MAX_CHARS)}…` : line;
+            pageErrors.push(truncated);
+            if (pageErrors.length > MAX_DIAGNOSTIC_LINES)
+                pageErrors.shift();
+        };
+        page.on('pageerror', (err) => recordPageError(err.message));
+        page.on('console', (msg) => {
+            if (msg.type() === 'error')
+                recordPageError(msg.text());
+        });
+        await page.goto(`http://127.0.0.1:${server.port}/?helixInspect=1`);
+        try {
+            await page.waitForFunction('window.__helixInspect?.ready === true', undefined, { timeout: timeoutMs });
+        }
+        catch {
+            const helperState = await page.evaluate(() => typeof window.__helixInspect === 'undefined' ? 'absent' : 'present');
+            throw new Error(`Timed out after ${timeoutMs}ms waiting for the inspect helper (window.__helixInspect) to become ready. ` +
+                composeInspectTimeoutDiagnosis(helperState, pageErrors));
+        }
+        if (settleMs > 0)
+            await page.waitForTimeout(settleMs);
+        onProgress(`helper ready — snapshotting after ${settleMs}ms settle`);
+        const snapshot = await page.evaluate(({ maxObjects }) => window.__helixInspect.snapshot(maxObjects !== undefined ? { maxObjects } : undefined), { maxObjects: opts.maxObjects });
+        return snapshot;
+    }
+    finally {
+        await browser?.close();
+        await server.close();
+    }
+}
+//# sourceMappingURL=snapshotWorld.js.map

package/dist/world/snapshotWorld.js.map

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

package/dist/world/zones.d.ts

@@ -0,0 +1,23 @@
+import type { WorldSnapshot } from './snapshotTypes';
+import { type Finding } from './analyze';
+export interface ZoneConfig {
+    id: string;
+    shape: 'box' | 'sphere';
+    center: [number, number, number];
+    size?: [number, number, number];
+    radius?: number;
+    tracks?: string;
+}
+export interface ZoneReport {
+    id: string;
+    extent: string;
+    /** Paths of objects whose AABB intersects the zone volume. */
+    touches: string[];
+    /** Surfaces a standing player could rest on while inside the zone. */
+    restSurfaces: string[];
+}
+export interface ZoneAnalysis {
+    findings: Finding[];
+    report: ZoneReport[];
+}
+export declare function analyzeZones(zones: ZoneConfig[], snapshot: WorldSnapshot): ZoneAnalysis;