@aura3d/engine 1.5.0 → 1.5.2

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

@@ -0,0 +1,217 @@
+/**
+ * Reusable AI driving: racing line, look-ahead steering, curvature-based speed.
+ *
+ * ## The defect this replaces
+ *
+ * Turbo's opponent was a route-local controller that steered only to null its
+ * lateral offset from the racing line:
+ *
+ * ```ts
+ * const steeringCorrection = -snapshot.signedTrackOffset * steeringGain;
+ * ```
+ *
+ * A pure proportional term on present error has no notion of where the track goes
+ * next. Approaching a corner it steers straight until it is already off the line,
+ * then over-corrects, which is why the opponent read as moving sideways and leaving
+ * the circuit. It also had no braking model tied to the corner ahead, so it entered
+ * every turn at cruise speed and understeered out of it. And because the kit's
+ * off-track handler pulls a certified car back toward the centreline, the recovery
+ * looked like the car being dragged rather than driving.
+ *
+ * This module drives the way a driver does: it samples the route **ahead** of the
+ * car, aims at a look-ahead point on the racing line, and sets a target speed from
+ * the curvature it is about to meet. It also detects being stuck and being off
+ * track, and recovers deliberately.
+ *
+ * Pure and deterministic: given the same route and the same seed it produces the
+ * same lap, so a race is reproducible and testable.
+ */
+const AGGRESSION_PROFILES = {
+    cautious: { paceScale: 0.82, cornerScale: 0.82, lineVariation: 0.05, reactionScale: 1.4 },
+    balanced: { paceScale: 0.92, cornerScale: 0.94, lineVariation: 0.1, reactionScale: 1 },
+    aggressive: { paceScale: 1, cornerScale: 1.06, lineVariation: 0.16, reactionScale: 0.7 }
+};
+/**
+ * Create a deterministic AI driver for a route.
+ */
+export function createVehicleDriverAi(route, config) {
+    /*
+     * A non-finite or non-positive route length makes every look-ahead progress NaN and
+     * the driver produces NaN steering, which reaches the renderer as an undefined
+     * position rather than as a visible error. Fail loudly at construction instead: a
+     * caller passing a route with no measurable length has a bug in its route adapter,
+     * and silently substituting 1 would hide it behind plausible-looking driving.
+     */
+    if (!Number.isFinite(route.length) || route.length <= 0) {
+        throw new Error(`createVehicleDriverAi requires a positive, finite route length; received ${String(route.length)}. Suggested fix: measure the racing-line polyline length and pass it as DriverRoute.length.`);
+    }
+    const aggression = config.aggression ?? "balanced";
+    const profile = AGGRESSION_PROFILES[aggression];
+    const maxSpeed = Math.max(0.01, config.maxSpeed);
+    const paceFraction = clamp(config.paceFraction ?? 0.92, 0.2, 1) * profile.paceScale;
+    const lookAheadSeconds = Math.max(0.1, config.lookAheadSeconds ?? 1.1);
+    const minLookAhead = Math.max(0.1, config.minLookAhead ?? Math.max(1, route.length * 0.01));
+    const lineGain = Math.max(0, config.lineGain ?? 1.6);
+    const headingGain = Math.max(0, config.headingGain ?? 1.5);
+    const corneringAcceleration = Math.max(0.5, config.corneringAcceleration ?? 9) * profile.cornerScale;
+    const reactionSeconds = Math.max(0, (config.reactionSeconds ?? 0.14) * profile.reactionScale);
+    let elapsed = 0;
+    let sinceDecision = 0;
+    let held = { throttle: 0, brake: 0, steer: 0, drift: false };
+    let decisionCount = 0;
+    let stuckSeconds = 0;
+    let recovering = false;
+    let telemetry = {
+        controller: "aura-vehicle-driver-ai",
+        aggression,
+        targetSpeed: maxSpeed * paceFraction,
+        lookAheadDistance: minLookAhead,
+        upcomingCurvature: 0,
+        cornerSpeedLimit: maxSpeed,
+        steerFromLine: 0,
+        steerFromHeading: 0,
+        recovering: false,
+        stuckSeconds: 0,
+        decisionCount: 0,
+        input: held
+    };
+    // Deterministic line variation, so two identical races produce identical laps.
+    let random = (config.seed ?? 1) >>> 0 || 1;
+    const nextRandom = () => {
+        random ^= random << 13;
+        random ^= random >>> 17;
+        random ^= random << 5;
+        return ((random >>> 0) / 0xffffffff) * 2 - 1;
+    };
+    /**
+     * Curvature of the racing line over the next `distance` units.
+     *
+     * Measured as heading change per unit distance across three samples, which is
+     * enough to distinguish a straight from a hairpin without differentiating a
+     * spline the route may not expose.
+     */
+    const curvatureAhead = (progress, distance) => {
+        const span = distance / Math.max(1e-6, route.length);
+        const a = route.sample(wrap(progress));
+        const b = route.sample(wrap(progress + span * 0.5));
+        const c = route.sample(wrap(progress + span));
+        const turn = Math.abs(angleDelta(b.heading, a.heading)) + Math.abs(angleDelta(c.heading, b.heading));
+        return turn / Math.max(1e-6, distance);
+    };
+    const decide = (state) => {
+        const speed = Math.abs(state.speed);
+        // Look-ahead distance grows with speed: at pace the driver plans further out.
+        const lookAheadDistance = Math.max(minLookAhead, speed * lookAheadSeconds);
+        const lookAheadProgress = wrap(state.progress + lookAheadDistance / Math.max(1e-6, route.length));
+        const aim = route.sample(lookAheadProgress);
+        const halfWidth = Math.max(1e-6, route.halfWidth(state.progress));
+        // Steering has two terms. Heading error aims the car at the look-ahead point,
+        // which is what makes it turn into a corner. Lateral error brings it back to
+        // the line. A controller with only the second term steers straight at a corner
+        // until it has already left the road -- the defect this replaces.
+        const bearingToAim = Math.atan2(aim.y - state.position.y, aim.x - state.position.x);
+        const headingError = angleDelta(bearingToAim, state.heading);
+        const steerFromHeading = clamp(headingError * headingGain, -1, 1);
+        // Lateral error normalized by road width, so a gain tuned on a wide circuit
+        // does not under-correct on a narrow one.
+        const steerFromLine = clamp((-state.signedTrackOffset / halfWidth) * lineGain, -1, 1);
+        // Racing-line variation keeps two AI cars from tracing the same path, and is
+        // deterministic so it does not make a race unreproducible.
+        const variation = Math.sin(elapsed * 0.74) * profile.lineVariation + nextRandom() * profile.lineVariation * 0.1;
+        // Corner speed from the curvature ahead: v = sqrt(a_lat / kappa).
+        const curvature = curvatureAhead(state.progress, lookAheadDistance);
+        const cornerSpeedLimit = curvature > 1e-4
+            ? Math.min(maxSpeed, Math.sqrt(corneringAcceleration / curvature))
+            : maxSpeed;
+        let targetSpeed = Math.min(maxSpeed * paceFraction, cornerSpeedLimit);
+        // Stuck and off-track recovery. A driver that has stopped moving is not
+        // "cruising slowly", it is stuck, and must be handled explicitly rather than
+        // relying on a kit to teleport it back to the centreline.
+        if (state.offTrack || stuckSeconds > 1.2) {
+            recovering = true;
+        }
+        else if (!state.offTrack && speed > maxSpeed * 0.18 && stuckSeconds === 0) {
+            recovering = false;
+        }
+        if (recovering) {
+            // Slow to a controllable speed and steer hard back toward the line.
+            targetSpeed = Math.min(targetSpeed, maxSpeed * 0.34);
+        }
+        const steer = clamp(recovering
+            ? steerFromLine * 1.4 + steerFromHeading * 0.6
+            : steerFromHeading + steerFromLine * 0.55 + variation, -1, 1);
+        // Throttle and brake from the speed error. Braking is proportional to the
+        // overspeed, so entering a corner too fast produces real braking rather than a
+        // binary coast.
+        const speedError = targetSpeed - speed;
+        const throttle = speedError > 0 ? clamp(speedError / Math.max(1e-6, maxSpeed * 0.25), 0, 1) : 0;
+        const brake = speedError < 0 ? clamp(-speedError / Math.max(1e-6, maxSpeed * 0.3), 0, 1) : 0;
+        // Drift only when genuinely cornering hard at speed; a stationary car
+        // handbraking is the kind of detail that makes a demo read as fake.
+        const drift = !recovering && Math.abs(steer) > 0.55 && speed > maxSpeed * 0.45;
+        telemetry = {
+            controller: "aura-vehicle-driver-ai",
+            aggression,
+            targetSpeed: round(targetSpeed),
+            lookAheadDistance: round(lookAheadDistance),
+            upcomingCurvature: round(curvature),
+            cornerSpeedLimit: round(cornerSpeedLimit),
+            steerFromLine: round(steerFromLine),
+            steerFromHeading: round(steerFromHeading),
+            recovering,
+            stuckSeconds: round(stuckSeconds),
+            decisionCount,
+            input: { throttle: round(throttle), brake: round(brake), steer: round(steer), drift }
+        };
+        return telemetry.input;
+    };
+    return {
+        kind: "aura-vehicle-driver-ai",
+        decide(dt, state) {
+            const step = Math.max(0, Math.min(0.1, dt));
+            elapsed += step;
+            sinceDecision += step;
+            // A stopped car accumulates stuck time; moving clears it.
+            stuckSeconds = Math.abs(state.speed) < maxSpeed * 0.05 ? stuckSeconds + step : 0;
+            // Reaction delay: hold the previous decision until the driver would react.
+            if (sinceDecision < reactionSeconds && decisionCount > 0)
+                return held;
+            sinceDecision = 0;
+            decisionCount += 1;
+            held = decide(state);
+            return held;
+        },
+        telemetry() {
+            return telemetry;
+        },
+        reset() {
+            elapsed = 0;
+            sinceDecision = 0;
+            decisionCount = 0;
+            stuckSeconds = 0;
+            recovering = false;
+            held = { throttle: 0, brake: 0, steer: 0, drift: false };
+            random = (config.seed ?? 1) >>> 0 || 1;
+        }
+    };
+}
+/** Smallest signed angle from `b` to `a`, in -pi..pi. */
+export function angleDelta(a, b) {
+    let delta = a - b;
+    while (delta > Math.PI)
+        delta -= Math.PI * 2;
+    while (delta < -Math.PI)
+        delta += Math.PI * 2;
+    return delta;
+}
+function wrap(progress) {
+    const value = progress % 1;
+    return value < 0 ? value + 1 : value;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, Number.isFinite(value) ? value : min));
+}
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+//# sourceMappingURL=VehicleDriverAi.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VehicleDriverAi.js","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/VehicleDriverAi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA2FH,MAAM,mBAAmB,GAKpB;IACH,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE;IACzF,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,EAAE;IACtF,UAAU,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE;CACzF,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAkB,EAAE,MAAoB;IAC5E;;;;;;OAMG;IACH,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,4EAA4E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,6FAA6F,CAC9L,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,UAAU,CAAC;IACnD,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,YAAY,IAAI,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;IACpF,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,gBAAgB,IAAI,GAAG,CAAC,CAAC;IACvE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAC5F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,IAAI,GAAG,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,WAAW,IAAI,GAAG,CAAC,CAAC;IAC3D,MAAM,qBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IACrG,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,eAAe,IAAI,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE9F,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,IAAI,GAAgB,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1E,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,SAAS,GAAoB;QAC/B,UAAU,EAAE,wBAAwB;QACpC,UAAU;QACV,WAAW,EAAE,QAAQ,GAAG,YAAY;QACpC,iBAAiB,EAAE,YAAY;QAC/B,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,QAAQ;QAC1B,aAAa,EAAE,CAAC;QAChB,gBAAgB,EAAE,CAAC;QACnB,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,CAAC;QAChB,KAAK,EAAE,IAAI;KACZ,CAAC;IACF,+EAA+E;IAC/E,IAAI,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,MAAM,IAAI,MAAM,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,MAAM,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,MAAM,IAAI,CAAC,CAAC;QACtB,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC,CAAC;IAEF;;;;;;OAMG;IACH,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAE,QAAgB,EAAU,EAAE;QACpE,MAAM,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;QACpD,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;QACrG,OAAO,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,KAAyB,EAAe,EAAE;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpC,8EAA8E;QAC9E,MAAM,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,GAAG,gBAAgB,CAAC,CAAC;QAC3E,MAAM,iBAAiB,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAClG,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAElE,8EAA8E;QAC9E,6EAA6E;QAC7E,+EAA+E;QAC/E,kEAAkE;QAClE,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACpF,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7D,MAAM,gBAAgB,GAAG,KAAK,CAAC,YAAY,GAAG,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,4EAA4E;QAC5E,0CAA0C;QAC1C,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,GAAG,SAAS,CAAC,GAAG,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEtF,6EAA6E;QAC7E,2DAA2D;QAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,aAAa,GAAG,GAAG,CAAC;QAEhH,kEAAkE;QAClE,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QACpE,MAAM,gBAAgB,GAAG,SAAS,GAAG,IAAI;YACvC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,qBAAqB,GAAG,SAAS,CAAC,CAAC;YAClE,CAAC,CAAC,QAAQ,CAAC;QACb,IAAI,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,YAAY,EAAE,gBAAgB,CAAC,CAAC;QAEtE,wEAAwE;QACxE,6EAA6E;QAC7E,0DAA0D;QAC1D,IAAI,KAAK,CAAC,QAAQ,IAAI,YAAY,GAAG,GAAG,EAAE,CAAC;YACzC,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,GAAG,QAAQ,GAAG,IAAI,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;YAC5E,UAAU,GAAG,KAAK,CAAC;QACrB,CAAC;QACD,IAAI,UAAU,EAAE,CAAC;YACf,oEAAoE;YACpE,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CACjB,UAAU;YACR,CAAC,CAAC,aAAa,GAAG,GAAG,GAAG,gBAAgB,GAAG,GAAG;YAC9C,CAAC,CAAC,gBAAgB,GAAG,aAAa,GAAG,IAAI,GAAG,SAAS,EACvD,CAAC,CAAC,EACF,CAAC,CACF,CAAC;QAEF,0EAA0E;QAC1E,+EAA+E;QAC/E,gBAAgB;QAChB,MAAM,UAAU,GAAG,WAAW,GAAG,KAAK,CAAC;QACvC,MAAM,QAAQ,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChG,MAAM,KAAK,GAAG,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,sEAAsE;QACtE,oEAAoE;QACpE,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAC;QAE/E,SAAS,GAAG;YACV,UAAU,EAAE,wBAAwB;YACpC,UAAU;YACV,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC;YAC/B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB,CAAC;YAC3C,iBAAiB,EAAE,KAAK,CAAC,SAAS,CAAC;YACnC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC;YACzC,aAAa,EAAE,KAAK,CAAC,aAAa,CAAC;YACnC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC;YACzC,UAAU;YACV,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC;YACjC,aAAa;YACb,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE;SACtF,CAAC;QACF,OAAO,SAAS,CAAC,KAAK,CAAC;IACzB,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,MAAM,CAAC,EAAE,EAAE,KAAK;YACd,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YAC5C,OAAO,IAAI,IAAI,CAAC;YAChB,aAAa,IAAI,IAAI,CAAC;YACtB,0DAA0D;YAC1D,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACjF,2EAA2E;YAC3E,IAAI,aAAa,GAAG,eAAe,IAAI,aAAa,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;YACtE,aAAa,GAAG,CAAC,CAAC;YAClB,aAAa,IAAI,CAAC,CAAC;YACnB,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,SAAS;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,KAAK;YACH,OAAO,GAAG,CAAC,CAAC;YACZ,aAAa,GAAG,CAAC,CAAC;YAClB,aAAa,GAAG,CAAC,CAAC;YAClB,YAAY,GAAG,CAAC,CAAC;YACjB,UAAU,GAAG,KAAK,CAAC;YACnB,IAAI,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YACzD,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,UAAU,CAAC,CAAS,EAAE,CAAS;IAC7C,IAAI,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC;IAClB,OAAO,KAAK,GAAG,IAAI,CAAC,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,OAAO,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,IAAI,CAAC,QAAgB;IAC5B,MAAM,KAAK,GAAG,QAAQ,GAAG,CAAC,CAAC;IAC3B,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACvC,CAAC;AAED,SAAS,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC"}

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

@@ -0,0 +1,146 @@
+/**
+ * World-anchored label rendering.
+ *
+ * ## The defect this fixes
+ *
+ * `labels.callout(...)` built a valid label node, the node reached the scene
+ * snapshot, and evidence counted it -- but nothing drew it. Labels were rendered
+ * only by `drawLabelNode`, which lives in the **canvas2d fallback** path. Every
+ * public route with a typed GLB takes the **production WebGL2** path, where
+ * `createProductionRuntimeRendererInput` collects model and primitive render
+ * items and ignores `kind: "label"` entirely.
+ *
+ * So the API was not partially implemented or mis-projected: it was implemented
+ * in the wrong render path. Every callout in every production route was silently
+ * dropped. The evidence collector counted label *nodes*, which is why reports
+ * showed labels present while the screen showed none.
+ *
+ * The fix is a real screen-space label layer: labels are world-anchored, projected
+ * with the scene's own view-projection matrix each frame, and drawn into a DOM
+ * overlay above the canvas. DOM is the right medium for text -- it is legible,
+ * accessible, and responsive -- but the *placement* is driven entirely by the 3D
+ * projection, so a label tracks its anchor while the camera moves. This is not a
+ * route-local DOM overlay: it is one reusable layer owned by the runtime.
+ *
+ * The projection math here is pure and unit-testable; only `mount` touches the DOM.
+ */
+export type LabelVec3 = readonly [number, number, number];
+/** Policy for labels whose anchor falls outside the viewport. */
+export type OffscreenPolicy = 
+/** Hide the label entirely. */
+"hide"
+/** Clamp to the nearest viewport edge, keeping the leader line pointing out. */
+ | "clamp"
+/** Keep drawing at the projected position even when offscreen. */
+ | "draw";
+export interface WorldLabel {
+    readonly id: string;
+    readonly text: string;
+    /** World point the label box is placed at. */
+    readonly anchor: LabelVec3;
+    /**
+     * World point a leader line points at, when it differs from the label's own
+     * position. A callout beside a part sets `anchor` to the label position and
+     * `leaderAnchor` to the part, so the line stays attached as the camera moves.
+     */
+    readonly leaderAnchor?: LabelVec3 | undefined;
+    /**
+     * Screen-space offset from the projected anchor, in CSS pixels. Lets a callout
+     * sit beside its target without moving the anchor the leader line points to.
+     */
+    readonly screenOffset?: readonly [number, number] | undefined;
+    readonly color?: string | undefined;
+    readonly background?: string | undefined;
+    /** Font size in CSS pixels at the default viewport. Scaled for compact viewports. */
+    readonly fontSize?: number | undefined;
+    readonly leader?: boolean | undefined;
+    readonly offscreenPolicy?: OffscreenPolicy | undefined;
+    /**
+     * Hide the label when its anchor is behind the camera. Defaults to true: a
+     * label for geometry behind the viewer is misleading.
+     */
+    readonly hideWhenBehindCamera?: boolean | undefined;
+    /** Screen-anchored HUD labels ignore the projection entirely. */
+    readonly screenAnchor?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
+}
+export interface LabelViewport {
+    readonly width: number;
+    readonly height: number;
+    /**
+     * Device pixel ratio is deliberately not used: labels are placed in CSS pixel
+     * space so they stay legible without per-device sizing.
+     */
+    readonly compact?: boolean | undefined;
+}
+export interface ProjectedLabel {
+    readonly id: string;
+    readonly text: string;
+    /** CSS-pixel position of the label box centre. */
+    readonly x: number;
+    readonly y: number;
+    /** CSS-pixel position of the leader-line endpoint (the projected anchor). */
+    readonly anchorX: number;
+    readonly anchorY: number;
+    readonly visible: boolean;
+    readonly clamped: boolean;
+    readonly behindCamera: boolean;
+    readonly fontSize: number;
+    readonly color: string;
+    readonly background: string;
+    readonly leader: boolean;
+    /** Normalized depth, 0 at the near plane. Used for draw ordering. */
+    readonly depth: number;
+}
+/**
+ * Project a world point through a column-major 4x4 view-projection matrix.
+ *
+ * Returns clip-space w alongside NDC so callers can detect points behind the
+ * camera (`w <= 0`) rather than silently drawing a mirrored label.
+ */
+export declare function projectWorldPoint(viewProjection: ArrayLike<number>, point: LabelVec3): {
+    readonly ndc: readonly [number, number, number];
+    readonly w: number;
+};
+/** Convert NDC to CSS-pixel screen coordinates for a viewport. */
+export declare function ndcToScreen(ndc: readonly [number, number, number], viewport: LabelViewport): readonly [number, number];
+/**
+ * Project a set of world labels into screen space.
+ *
+ * Pure: no DOM. This is the function tests assert on, so label placement is
+ * verified by arithmetic rather than by looking at a screenshot.
+ */
+export declare function projectWorldLabels(labels: readonly WorldLabel[], viewProjection: ArrayLike<number>, viewport: LabelViewport): readonly ProjectedLabel[];
+/**
+ * Resolve overlapping labels by nudging later ones vertically.
+ *
+ * Collision avoidance is a documented option on the label API, so it must
+ * actually happen. Labels are sorted front-to-back so nearer labels keep their
+ * requested position and farther ones move.
+ */
+export declare function resolveLabelCollisions(labels: readonly ProjectedLabel[], options?: {
+    readonly minGap?: number | undefined;
+}): readonly ProjectedLabel[];
+export interface WorldLabelLayerHost {
+    /** Element the layer is appended to; normally the canvas's parent. */
+    readonly container: HTMLElement;
+    /** Canvas the labels are drawn over, used for CSS-pixel viewport size. */
+    readonly canvas: HTMLCanvasElement;
+}
+export interface WorldLabelLayer {
+    /** Replace the label set. */
+    setLabels(labels: readonly WorldLabel[]): void;
+    /** Reproject and redraw with the current view-projection matrix. */
+    update(viewProjection: ArrayLike<number>): void;
+    /** Most recent projection result, for evidence and tests. */
+    snapshot(): readonly ProjectedLabel[];
+    dispose(): void;
+}
+/**
+ * Mount the screen-space label layer.
+ *
+ * Uses `pointer-events: none` so labels never intercept scene interaction, and
+ * `aria-live="off"` with per-label `role="note"` so a screen reader can read the
+ * annotations without announcing every camera-driven reposition.
+ */
+export declare function createWorldLabelLayer(host: WorldLabelLayerHost): WorldLabelLayer;
+//# sourceMappingURL=WorldLabelRenderer.d.ts.map

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

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