@aura3d/engine 2.0.4 → 3.0.0

package/dist/engine/agent-api/GameFeel.js

@@ -0,0 +1,226 @@
+/**
+ * Generalized game-feel kit (muse3jsparity-PRD F3).
+ *
+ * Generalizes the combat-proven pieces: `hitStop` durations come from the
+ * fighting kit (`game-kits/fighting.ts`: light 0.045s, heavy 0.07s,
+ * special 0.1s) and the pixel path reuses the `createGameEffects` kinds
+ * (`hit-spark`, `impact-flash`, `dash-trail`, `ground-dust`, ...), so every
+ * effect below resolves to real scene nodes through `nodes()` — never DOM,
+ * canvas, or CSS fakes (boundaries rule).
+ *
+ * This module is engine-pure and owns no renderer: the effects controller is
+ * injected through {@link GameFeelEffectsPort}, which `createGameEffects`
+ * (in `GameRuntime.ts`) satisfies structurally. A kit without a wired
+ * controller refuses pixel-backed triggers with an explicit receipt instead
+ * of faking success. All triggers are frame-budgeted and every trigger
+ * returns a receipt; `snapshot()` is the telemetry surface.
+ */
+/** Combat-proven hit-stop defaults, generalized (fighting kit values). */
+export const GAME_FEEL_HIT_STOP_LIGHT_S = 0.045;
+export const GAME_FEEL_HIT_STOP_HEAVY_S = 0.07;
+export const GAME_FEEL_HIT_STOP_SPECIAL_S = 0.1;
+export const GAME_FEEL_HIT_STOP_DEFAULT_S = 0.06;
+function assertFinite(value, api, field) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError(`${api} ${field} must be finite (received ${String(value)}).`);
+    }
+}
+function nowMs() {
+    if (typeof performance !== "undefined" && typeof performance.now === "function")
+        return performance.now();
+    return Date.now();
+}
+export function createGameFeel(options = {}) {
+    const budgetMs = options.budgetMs ?? 2;
+    assertFinite(budgetMs, "gameFeel", "budgetMs");
+    if (budgetMs < 0)
+        throw new RangeError("gameFeel budgetMs must be >= 0.");
+    let enabled = options.enabled ?? true;
+    const effects = options.effects;
+    let slowMoScale = 1;
+    let slowMoRemainingMs = 0;
+    let hitStopRemainingMs = 0;
+    let flashRemainingMs = 0;
+    let lineIntensity = 0;
+    let lineRemainingMs = 0;
+    let dustSpawned = 0;
+    let updates = 0;
+    let lastMs = 0;
+    let maxMs = 0;
+    let overBudgetCount = 0;
+    const disabled = (effect) => ({
+        accepted: false,
+        reason: `gameFeel.${effect} rejected: kit disabled (setEnabled(true) to resume).`
+    });
+    const unwired = (effect) => ({
+        accepted: false,
+        reason: `gameFeel.${effect} rejected: no effects controller wired (pass options.effects).`
+    });
+    const timeScale = () => {
+        if (hitStopRemainingMs > 0)
+            return 0;
+        if (slowMoRemainingMs > 0)
+            return slowMoScale;
+        return 1;
+    };
+    const budget = () => ({
+        lastMs,
+        maxMs,
+        budgetMs,
+        overBudget: lastMs > budgetMs,
+        overBudgetCount,
+        updates
+    });
+    const snap = () => {
+        const effectsSnapshot = effects?.snapshot();
+        return {
+            kind: "aura-game-feel",
+            enabled,
+            timeScale: timeScale(),
+            frozen: hitStopRemainingMs > 0,
+            slowMoActive: slowMoRemainingMs > 0,
+            hitStopActive: hitStopRemainingMs > 0,
+            flashActive: flashRemainingMs > 0,
+            lineIntensity: lineRemainingMs > 0 ? lineIntensity : 0,
+            dustSpawned,
+            effectsActive: effectsSnapshot?.active ?? 0,
+            effectsSpawned: effectsSnapshot?.spawned ?? 0,
+            budget: budget()
+        };
+    };
+    return {
+        get effectsWired() {
+            return effects !== undefined;
+        },
+        setEnabled(next) {
+            enabled = next === true;
+            if (!enabled) {
+                slowMoRemainingMs = 0;
+                hitStopRemainingMs = 0;
+                flashRemainingMs = 0;
+                lineRemainingMs = 0;
+                lineIntensity = 0;
+                slowMoScale = 1;
+            }
+        },
+        slowMo(scale, durationMs) {
+            const api = "gameFeel.slowMo";
+            assertFinite(scale, api, "scale");
+            assertFinite(durationMs, api, "durationMs");
+            if (scale < 0 || scale > 1)
+                throw new RangeError(`${api} scale must be in [0, 1].`);
+            if (durationMs <= 0)
+                throw new RangeError(`${api} durationMs must be > 0.`);
+            if (!enabled)
+                return disabled("slowMo");
+            slowMoScale = scale;
+            slowMoRemainingMs = durationMs;
+            return { accepted: true };
+        },
+        hitStop(durationMs) {
+            const api = "gameFeel.hitStop";
+            assertFinite(durationMs, api, "durationMs");
+            if (durationMs <= 0)
+                throw new RangeError(`${api} durationMs must be > 0.`);
+            if (!enabled)
+                return disabled("hitStop");
+            // Generalized from the fighting kit: a full freeze for the window.
+            hitStopRemainingMs = Math.max(hitStopRemainingMs, durationMs);
+            return { accepted: true };
+        },
+        damageFlash(color, position = [0, 1, 0]) {
+            const api = "gameFeel.damageFlash";
+            if (typeof color !== "string" || color.length === 0) {
+                throw new RangeError(`${api} color must be a non-empty string.`);
+            }
+            if (!enabled)
+                return disabled("damageFlash");
+            if (!effects)
+                return unwired("damageFlash");
+            const effect = effects.spawn("impact-flash", position, { color, intensity: 1, duration: 0.12 });
+            flashRemainingMs = 120;
+            return { accepted: true, effectId: effect.id };
+        },
+        speedLines(intensity, position = [0, 1, -1]) {
+            const api = "gameFeel.speedLines";
+            assertFinite(intensity, api, "intensity");
+            if (intensity < 0 || intensity > 1)
+                throw new RangeError(`${api} intensity must be in [0, 1].`);
+            if (!enabled)
+                return disabled("speedLines");
+            if (!effects)
+                return unwired("speedLines");
+            const effect = effects.spawn(intensity > 0.6 ? "slash-trail" : "dash-trail", position, {
+                intensity,
+                duration: 0.28
+            });
+            lineIntensity = intensity;
+            lineRemainingMs = 280;
+            return { accepted: true, effectId: effect.id };
+        },
+        landingDust(position) {
+            const api = "gameFeel.landingDust";
+            if (!Array.isArray(position) || position.length !== 3 || position.some((c) => !Number.isFinite(c))) {
+                throw new RangeError(`${api} position must be a finite [x, y, z] tuple.`);
+            }
+            if (!enabled)
+                return disabled("landingDust");
+            if (!effects)
+                return unwired("landingDust");
+            const effect = effects.spawn("ground-dust", position, { intensity: 0.8, duration: 0.34 });
+            dustSpawned += 1;
+            return { accepted: true, effectId: effect.id };
+        },
+        effectiveDt(dtMs) {
+            assertFinite(dtMs, "gameFeel.effectiveDt", "dtMs");
+            return Math.max(0, dtMs) * timeScale();
+        },
+        update(dtMs) {
+            assertFinite(dtMs, "gameFeel.update", "dtMs");
+            const started = nowMs();
+            const step = Math.max(0, dtMs);
+            slowMoRemainingMs = Math.max(0, slowMoRemainingMs - step);
+            if (slowMoRemainingMs === 0)
+                slowMoScale = 1;
+            hitStopRemainingMs = Math.max(0, hitStopRemainingMs - step);
+            flashRemainingMs = Math.max(0, flashRemainingMs - step);
+            lineRemainingMs = Math.max(0, lineRemainingMs - step);
+            if (lineRemainingMs === 0)
+                lineIntensity = 0;
+            effects?.update(step / 1000);
+            updates += 1;
+            lastMs = nowMs() - started;
+            maxMs = Math.max(maxMs, lastMs);
+            if (lastMs > budgetMs)
+                overBudgetCount += 1;
+            return snap();
+        },
+        snapshot: snap,
+        nodes() {
+            return effects?.nodes() ?? [];
+        },
+        clear() {
+            effects?.clear();
+            slowMoRemainingMs = 0;
+            hitStopRemainingMs = 0;
+            flashRemainingMs = 0;
+            lineRemainingMs = 0;
+            lineIntensity = 0;
+            slowMoScale = 1;
+        }
+    };
+}
+/**
+ * Root-bridge namespace (wiring lives in `agent-api/index.ts`, owned by the
+ * bridge sibling — this object is the exact surface to expose as `gameFeel`).
+ */
+export const gameFeelBuilders = {
+    create: createGameFeel,
+    hitStopDefaults: {
+        light: GAME_FEEL_HIT_STOP_LIGHT_S,
+        heavy: GAME_FEEL_HIT_STOP_HEAVY_S,
+        special: GAME_FEEL_HIT_STOP_SPECIAL_S,
+        default: GAME_FEEL_HIT_STOP_DEFAULT_S
+    }
+};
+//# sourceMappingURL=GameFeel.js.map

package/dist/engine/agent-api/GameFeel.js.map

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

package/dist/engine/agent-api/LabelTelemetry.d.ts

@@ -0,0 +1,108 @@
+import type { AuraLabelNode } from "./index.js";
+import type { ProjectedLabel } from "./WorldLabelRenderer.js";
+/**
+ * Label telemetry for the three text buckets (muse3jsparity-PRD N4).
+ *
+ * N4 ends the DOM-vs-3D ambiguity with three buckets and three proofs:
+ *
+ * 1. Accessible DOM (`ui.*`) — screen-reader text, never projected. Counted
+ *    from the scene as `hud` labels plus `ui.*` bindings, not from pixels.
+ * 2. World-anchored screen-space labels (`labels.billboard/anchor/axisTick/
+ *    callout`) — DOM boxes placed by 3D projection. Proven by
+ *    `collectLabelTelemetry` below: placed-vs-offscreen counts per route,
+ *    computed from the projected set, not the node set. Counting nodes is
+ *    what let silently-dropped callouts stay green.
+ * 3. Lit/occluded 3D text (G1 SDF) — in-world quads. Proven by
+ *    `textPixelBacked`, owned by `packages/rendering/src/SdfText.ts`.
+ *
+ * ## CSS2D/CSS3D
+ *
+ * Explicit 2.1 decision (see `CSS2D_OUT_OF_SCOPE`): NO `CSS2DRenderer` /
+ * `CSS3DRenderer` parity. Verified: zero `CSS2D`/`CSS3D` references exist in
+ * `packages/`. Game annotation needs are covered by buckets 2 and 3; the
+ * three-compat migration lab documents the manual CSS2D/3D mapping for
+ * importers. Revisit only with a named customer workload.
+ *
+ * Pure: no DOM. Takes scene nodes plus the projected set (from
+ * `AuraDiagnostics.labels`) and returns counts. The engine bridge embeds the
+ * result in diagnostics; route-health enforces it per route.
+ */
+/** Collision-avoidance role: HUD copy never collides, ticks are dense, annotations steer. */
+export type LabelTelemetryRole = "hud" | "annotation" | "tick";
+export declare function labelTelemetryRoleFor(label: AuraLabelNode["label"]): LabelTelemetryRole;
+export interface LabelTelemetryByRole {
+    readonly declared: number;
+    readonly placed: number;
+    readonly offscreen: number;
+}
+export interface LabelTelemetry {
+    readonly kind: "aura-label-telemetry";
+    /** Labels declared in the scene snapshot. */
+    readonly declared: number;
+    /** Labels actually placed on screen this frame (`visible === true`). */
+    readonly placed: number;
+    /** Labels declared but not on screen (hidden, clamped-away, behind camera, occlusion-hidden). */
+    readonly offscreen: number;
+    readonly behindCamera: number;
+    readonly clamped: number;
+    readonly occludedDimmed: number;
+    readonly byRole: Readonly<Record<LabelTelemetryRole, LabelTelemetryByRole>>;
+    /**
+     * Fail-closed gate signal for route-health: a route that declares labels
+     * but places none fails. A route with no labels passes vacuously.
+     */
+    readonly placesLabels: boolean;
+}
+/**
+ * Join scene label nodes with their projected results by node id.
+ *
+ * Ids must match `worldLabelsFromSnapshot` exactly: `node.name`, else
+ * `${node.label}-${position}` where position is 1-based in flattened snapshot
+ * order. Pass nodes in that same order; a mismatched id counts the label as
+ * offscreen rather than inventing a placement.
+ */
+export declare function collectLabelTelemetry(nodes: readonly AuraLabelNode[], projected: readonly ProjectedLabel[]): LabelTelemetry;
+export interface LabelCollisionTuning {
+    readonly role: LabelTelemetryRole;
+    /** Minimum vertical gap in CSS pixels used by `resolveLabelCollisions`. */
+    readonly minGapPx: number;
+    /** Whether collision avoidance runs for this role at all. */
+    readonly avoidanceEnabled: boolean;
+    readonly note: string;
+}
+/**
+ * Per-role collision-avoidance tuning (N4 task 2).
+ *
+ * HUD copy is screen-anchored and never collides; axis ticks are dense and get
+ * the tightest gap; annotations keep the default gap so leaders stay readable.
+ */
+export declare function tuneLabelCollision(role: LabelTelemetryRole): LabelCollisionTuning;
+export interface TextBucketSummary {
+    /** Bucket 1: accessible DOM (`ui.*` bindings + `hud` labels). UI-only, never 3D proof. */
+    readonly accessibleDom: number;
+    /** Bucket 2: world-anchored screen-space labels placed this frame. */
+    readonly worldAnchoredPlaced: number;
+    /** Bucket 3: lit/occluded SDF 3D text quads submitted this frame. */
+    readonly sdfTexts: number;
+    readonly note: string;
+}
+/** Three buckets, three numbers — never merged, per the inventory rule. */
+export declare function summarizeTextBuckets(input: {
+    readonly accessibleDom: number;
+    readonly worldAnchoredPlaced: number;
+    readonly sdfTexts: number;
+}): TextBucketSummary;
+/**
+ * The explicit 2.1 decision: NO `CSS2DRenderer`/`CSS3DRenderer` parity.
+ * Game annotation needs are covered by world-anchored labels + G1 SDF text;
+ * the three-compat migration lab documents the manual CSS2D/3D mapping for
+ * importers. Revisit only with a named customer workload.
+ */
+export declare const CSS2D_OUT_OF_SCOPE: {
+    readonly decision: "no-css2d-css3d-parity";
+    readonly renderers: readonly ["CSS2DRenderer", "CSS3DRenderer"];
+    readonly coveredBy: readonly ["world-anchored labels", "G1 SDF text"];
+    readonly importerPath: "three-compat migration lab documents the manual CSS2D/3D mapping";
+    readonly revisit: "named customer workload only";
+};
+//# sourceMappingURL=LabelTelemetry.d.ts.map

package/dist/engine/agent-api/LabelTelemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LabelTelemetry.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/LabelTelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,6FAA6F;AAC7F,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;AAE/D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,kBAAkB,CAIvF;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iGAAiG;IACjG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC5E;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,SAAS,EAAE,SAAS,cAAc,EAAE,GACnC,cAAc,CAwChB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,CAuBjF;AAED,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,iBAAiB,CAUpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC"}

package/dist/engine/agent-api/LabelTelemetry.js

@@ -0,0 +1,116 @@
+export function labelTelemetryRoleFor(label) {
+    if (label === "hud")
+        return "hud";
+    if (label === "axis-tick")
+        return "tick";
+    return "annotation";
+}
+/**
+ * Join scene label nodes with their projected results by node id.
+ *
+ * Ids must match `worldLabelsFromSnapshot` exactly: `node.name`, else
+ * `${node.label}-${position}` where position is 1-based in flattened snapshot
+ * order. Pass nodes in that same order; a mismatched id counts the label as
+ * offscreen rather than inventing a placement.
+ */
+export function collectLabelTelemetry(nodes, projected) {
+    const byId = new Map(projected.map((label) => [label.id, label]));
+    const byRole = {
+        hud: { declared: 0, placed: 0, offscreen: 0 },
+        annotation: { declared: 0, placed: 0, offscreen: 0 },
+        tick: { declared: 0, placed: 0, offscreen: 0 }
+    };
+    let behindCamera = 0;
+    let clamped = 0;
+    let occludedDimmed = 0;
+    let placedCount = 0;
+    nodes.forEach((node, index) => {
+        const role = labelTelemetryRoleFor(node.label);
+        const slot = byRole[role];
+        byRole[role] = { ...slot, declared: slot.declared + 1 };
+        const id = node.name ?? `${node.label}-${index + 1}`;
+        const result = byId.get(id);
+        const placed = result?.visible === true;
+        if (placed) {
+            placedCount += 1;
+            byRole[role] = { ...byRole[role], placed: byRole[role].placed + 1 };
+            if (result.clamped)
+                clamped += 1;
+            if (result.occluded && result.occlusionOpacity < 1)
+                occludedDimmed += 1;
+        }
+        else {
+            byRole[role] = { ...byRole[role], offscreen: byRole[role].offscreen + 1 };
+            if (result?.behindCamera === true)
+                behindCamera += 1;
+        }
+    });
+    const declared = nodes.length;
+    return {
+        kind: "aura-label-telemetry",
+        declared,
+        placed: placedCount,
+        offscreen: declared - placedCount,
+        behindCamera,
+        clamped,
+        occludedDimmed,
+        byRole,
+        placesLabels: declared === 0 || placedCount > 0
+    };
+}
+/**
+ * Per-role collision-avoidance tuning (N4 task 2).
+ *
+ * HUD copy is screen-anchored and never collides; axis ticks are dense and get
+ * the tightest gap; annotations keep the default gap so leaders stay readable.
+ */
+export function tuneLabelCollision(role) {
+    if (role === "hud") {
+        return {
+            role,
+            minGapPx: 0,
+            avoidanceEnabled: false,
+            note: "HUD labels are screen-anchored; collision avoidance is disabled so copy never moves."
+        };
+    }
+    if (role === "tick") {
+        return {
+            role,
+            minGapPx: 2,
+            avoidanceEnabled: true,
+            note: "Axis ticks are dense by design; tight gap with front-to-back priority."
+        };
+    }
+    return {
+        role,
+        minGapPx: 4,
+        avoidanceEnabled: true,
+        note: "Annotations keep the default gap so leader lines stay attached to their subject."
+    };
+}
+/** Three buckets, three numbers — never merged, per the inventory rule. */
+export function summarizeTextBuckets(input) {
+    for (const [key, value] of Object.entries(input)) {
+        if (!Number.isInteger(value) || value < 0) {
+            throw new Error(`Aura3D text bucket "${key}" must be a non-negative integer.`);
+        }
+    }
+    return {
+        ...input,
+        note: "Accessible DOM, world-anchored labels, and SDF 3D text are separate capabilities with separate proof."
+    };
+}
+/**
+ * The explicit 2.1 decision: NO `CSS2DRenderer`/`CSS3DRenderer` parity.
+ * Game annotation needs are covered by world-anchored labels + G1 SDF text;
+ * the three-compat migration lab documents the manual CSS2D/3D mapping for
+ * importers. Revisit only with a named customer workload.
+ */
+export const CSS2D_OUT_OF_SCOPE = {
+    decision: "no-css2d-css3d-parity",
+    renderers: ["CSS2DRenderer", "CSS3DRenderer"],
+    coveredBy: ["world-anchored labels", "G1 SDF text"],
+    importerPath: "three-compat migration lab documents the manual CSS2D/3D mapping",
+    revisit: "named customer workload only"
+};
+//# sourceMappingURL=LabelTelemetry.js.map

package/dist/engine/agent-api/LabelTelemetry.js.map

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

package/dist/engine/agent-api/NavigationCrowds.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Structural mirrors of the `@aura3d/navigation-recast` value-object shapes,
+ * kept LOCAL (never imported) so the packed engine carries no hard link —
+ * type-level or runtime — to the optional peer. The peer stays resolvable
+ * through the bare specifier in `loadNavigationPeer` below (dynamic import,
+ * fail-closed when absent) and through workspace aliases in source builds.
+ * If the peer shapes change, update these mirrors to match; assignability
+ * with the real peer holds structurally (loader returns are covariant).
+ */
+type NavigationVec3 = readonly [number, number, number];
+interface NavigationTriangleSoup {
+    readonly positions: readonly number[] | Float32Array;
+    readonly indices: readonly number[] | Uint32Array;
+}
+interface NavigationPathResult {
+    readonly success: boolean;
+    readonly points: readonly NavigationVec3[];
+    readonly error?: string;
+}
+interface NavigationCrowdAgentOptions {
+    readonly radius?: number;
+    readonly height?: number;
+    readonly maxAcceleration?: number;
+    readonly maxSpeed?: number;
+    readonly collisionQueryRange?: number;
+    readonly pathOptimizationRange?: number;
+    readonly separationWeight?: number;
+}
+interface RecastCrowdAgentState {
+    readonly position: NavigationVec3;
+    readonly velocity: NavigationVec3;
+    readonly speed: number;
+}
+interface RecastNavigationOptions {
+    readonly moduleLoader?: () => Promise<unknown>;
+    readonly generatorLoader?: () => Promise<unknown>;
+}
+/**
+ * Root navigation + crowds builders (muse3jsparity-PRD O1).
+ *
+ * Recast stays an OPTIONAL peer: this module never statically imports
+ * `@aura3d/navigation-recast` (the optional-boundary test forbids it from
+ * engine manifests, and a static value import would hard-require the peer for
+ * every route). The peer loads through an injected loader — tests inject
+ * fakes, routes rely on the default dynamic import — and every failure keeps
+ * the package's fail-closed "optional peer unavailable + install step" error.
+ * Nothing here falls back to a silent no-op navigator.
+ */
+/**
+ * Minimal structural peer surface: the real `createRecastNavigation` return
+ * satisfies this (extra methods allowed); fakes implement only what the root
+ * builders call. This keeps unit tests hermetic without importing the
+ * optional package.
+ */
+export interface AuraNavigationPeer {
+    createRecastNavigation(options?: RecastNavigationOptions): Promise<{
+        generateSolo(input: NavigationTriangleSoup, config: Record<string, number | string | boolean>): {
+            computePath(from: NavigationVec3, to: NavigationVec3): NavigationPathResult;
+            createCrowd(maxAgents: number, maxAgentRadius: number): {
+                readonly maxAgents: number;
+                count(): number;
+                addAgent(position: NavigationVec3, options?: NavigationCrowdAgentOptions): unknown;
+                setTarget(agent: unknown, target: NavigationVec3): boolean;
+                update(dt: number): void;
+                agentStates(): readonly RecastCrowdAgentState[];
+            };
+        };
+    }>;
+}
+export interface AuraNavigationPeerLoaders extends RecastNavigationOptions {
+    /**
+     * Fully hermetic peer injection for tests: when supplied, no dynamic
+     * import runs at all, so the suite never needs the optional package.
+     */
+    readonly peer?: AuraNavigationPeer;
+}
+export interface AuraNavMeshBakeOptions {
+    readonly positions: readonly number[] | Float32Array;
+    readonly indices: readonly number[] | Uint32Array;
+    readonly settings?: Record<string, number | string | boolean>;
+}
+export interface AuraCrowdCreateOptions {
+    readonly maxAgents: number;
+    readonly maxAgentRadius: number;
+}
+export type AuraNavMeshHandle = Awaited<ReturnType<AuraNavigationPeer["createRecastNavigation"]>> extends {
+    generateSolo(input: NavigationTriangleSoup, config: Record<string, number | string | boolean>): infer M;
+} ? M : never;
+export type AuraCrowdHandle = AuraNavMeshHandle extends {
+    createCrowd(maxAgents: number, maxAgentRadius: number): infer C;
+} ? C : never;
+declare function bakeNavMesh(options: AuraNavMeshBakeOptions, loaders?: AuraNavigationPeerLoaders): Promise<AuraNavMeshHandle>;
+declare function queryPath(mesh: AuraNavMeshHandle, from: NavigationVec3, to: NavigationVec3): NavigationPathResult;
+declare function navigationIsAvailable(loaders?: AuraNavigationPeerLoaders): Promise<boolean>;
+export declare const navigation: {
+    readonly bake: typeof bakeNavMesh;
+    readonly path: typeof queryPath;
+    readonly isAvailable: typeof navigationIsAvailable;
+};
+declare function createCrowd(mesh: AuraNavMeshHandle, options: AuraCrowdCreateOptions): AuraCrowdHandle;
+declare function crowdAgents(crowd: AuraCrowdHandle): readonly RecastCrowdAgentState[];
+export declare const crowds: {
+    readonly create: typeof createCrowd;
+    readonly addAgent: (crowd: AuraCrowdHandle, position: NavigationVec3, options?: NavigationCrowdAgentOptions) => unknown;
+    readonly setTarget: (crowd: AuraCrowdHandle, agent: unknown, target: NavigationVec3) => boolean;
+    readonly update: (crowd: AuraCrowdHandle, dt: number) => void;
+    readonly agents: typeof crowdAgents;
+    readonly count: (crowd: AuraCrowdHandle) => number;
+    readonly maxAgents: (crowd: AuraCrowdHandle) => number;
+    readonly diagnostics: typeof describeCrowd;
+};
+/** LOD tier per agent: full actors near, billboard/marker impostors past `farDistance`. */
+export type AuraCrowdLodTier = "near" | "mid" | "impostor" | "unknown";
+export interface AuraCrowdLodOptions {
+    /** Camera position in the same space as agent positions. Without it every tier is "unknown". */
+    readonly camera?: NavigationVec3;
+    /** At or below this distance an agent renders full (default 6). */
+    readonly nearDistance?: number;
+    /** Past this distance an agent falls back to an impostor/marker (default 14). */
+    readonly farDistance?: number;
+}
+export interface AuraCrowdAgentLod {
+    readonly position: NavigationVec3;
+    readonly distance: number | null;
+    readonly tier: AuraCrowdLodTier;
+}
+export interface AuraCrowdDiagnostics {
+    readonly count: number;
+    readonly maxAgents: number;
+    /** True once `addAgent` would throw instead of spawning (fail-closed cap). */
+    readonly atCap: boolean;
+    /** Present exactly when `atCap` — the over-budget warning for route evidence. */
+    readonly capWarning?: string;
+    readonly tiers: Record<AuraCrowdLodTier, number>;
+    readonly agents: readonly AuraCrowdAgentLod[];
+}
+/**
+ * O1 crowd LOD + cap diagnostics over LIVE crowd state (never the fixture sampler).
+ *
+ * Distances are Euclidean from `camera` to each live agent position; tiers split at
+ * `nearDistance`/`farDistance`. Throws on inverted bounds so a misconfigured LOD
+ * can never silently report every agent as near.
+ */
+export declare function describeCrowd(crowd: AuraCrowdHandle, options?: AuraCrowdLodOptions): AuraCrowdDiagnostics;
+export {};
+//# sourceMappingURL=NavigationCrowds.d.ts.map

package/dist/engine/agent-api/NavigationCrowds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavigationCrowds.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/NavigationCrowds.ts"],"names":[],"mappings":"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"}