@aura3d/engine 1.4.4 → 1.5.0

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

@@ -0,0 +1,127 @@
+/**
+ * Declarative subject framing derived from typed asset metadata.
+ *
+ * ## Why this exists
+ *
+ * Route code kept encoding *specific assets* into visual constants. Turbo's chase camera height was
+ * `0.46`, justified in a comment that recited one asset's bounds ("176.35 units tall over a 377.94
+ * longest axis"). Its `CAR_SCENE_HEIGHT` was worse: hardcoded to `2.209 / 6.958`, the bounds of a hero
+ * asset that had already been replaced twice, so every swap silently mis-seated the new car.
+ *
+ * The failure mode is structural, not careless. A number that is *correct* for one asset looks like a
+ * tuned design constant, so it survives review and survives asset swaps. The only durable fix is for
+ * routes to declare **intent** -- "frame a rear chase view where the subject occupies 25-40% of frame
+ * height and the lower silhouette stays visible" -- and let reusable code derive the numbers from the
+ * typed manifest.
+ *
+ * These helpers are pure and dependency-free so they can be unit tested against synthetic bounds and
+ * reused by any genre. They deliberately do **not** know about racing, platformers, or any route.
+ */
+import { type SceneAssetLike, type SceneBounds } from "./SceneGroundingUtils.js";
+/** Rendered dimensions of a subject after the renderer's fit scale is applied. */
+export interface SubjectRenderedSize {
+    /** Rendered extent along each axis, in world units. */
+    readonly size: readonly [number, number, number];
+    /** Rendered height (Y extent). */
+    readonly height: number;
+    /** Rendered longest axis. */
+    readonly maxDimension: number;
+    /** Rendered extent along the subject's longitudinal (longest horizontal) axis. */
+    readonly length: number;
+    /** Uniform scale the renderer applies to reach the requested fit. */
+    readonly fitScale: number;
+}
+export interface SubjectFitRequest {
+    /** Fit the subject's height to this world-unit value. */
+    readonly targetHeight?: number | undefined;
+    /** Fit the subject's longest axis to this world-unit value. */
+    readonly targetMaxDimension?: number | undefined;
+    /** Fit the subject's longitudinal (longest horizontal) axis to this world-unit value. */
+    readonly targetLength?: number | undefined;
+}
+/**
+ * Resolve what a subject actually measures once fit, straight from typed bounds.
+ *
+ * This replaces the `CAR_TARGET_MAX_DIMENSION * (BOUNDS_Y / BOUNDS_LONGEST)` arithmetic that routes
+ * were open-coding, and which is exactly where the stale-literal defect lived.
+ */
+export declare function resolveSubjectRenderedSize(asset: SceneAssetLike, request: SubjectFitRequest): SubjectRenderedSize;
+/** Bounds-level form of {@link resolveSubjectRenderedSize}, for fixtures and tests. */
+export declare function resolveSubjectRenderedSizeFromBounds(bounds: SceneBounds, request: SubjectFitRequest): SubjectRenderedSize;
+/**
+ * A route's framing *intent*, expressed without reference to any asset's dimensions.
+ *
+ * `subjectVerticalOccupancy` is the contract that matters: it states how much of the frame's height
+ * the subject should fill. Everything else (camera height, distance) is derived to satisfy it.
+ */
+export interface ChaseFramingIntent extends SubjectFitRequest {
+    /** Vertical fraction of the frame the subject should occupy, as `[min, max]`. */
+    readonly subjectVerticalOccupancy: readonly [number, number];
+    /** Vertical field of view in degrees. */
+    readonly fov: number;
+    /**
+     * Fraction of the subject's height the camera should sit at, measured from its contact plane.
+     *
+     * Expressed as a fraction rather than a world-unit height precisely so it survives asset swaps.
+     * The default 0.9 places the eye just above the subject's mid-height: high enough to see the ground
+     * ahead, low enough that the subject's own roof line does not occlude its lower silhouette.
+     */
+    readonly eyeHeightFraction?: number | undefined;
+    /**
+     * Require the lowest `lowerSilhouetteFraction` of the subject to remain unoccluded by its own upper
+     * body, which is what makes wheels, feet, or landing gear readable.
+     */
+    readonly lowerSilhouetteFraction?: number | undefined;
+    /**
+     * Require the subject's lower side features (wheels, feet) to be readable from this framing.
+     *
+     * A dead-astern or dead-ahead chase view cannot show them: the subject's own bodywork occludes its
+     * lower flanks by construction. This was learned the hard way — a hero car's tyres were reported as
+     * "not rendering" when in fact the renderer drew all of them and the camera was simply looking down
+     * the one axis where they cannot appear.
+     *
+     * When set, `resolveChaseFraming` derives a lateral offset large enough to bring the flank into view.
+     */
+    readonly requireLowerSideFeatureVisibility?: boolean | undefined;
+}
+export interface ChaseFraming {
+    /** Camera height above the subject's contact plane. */
+    readonly height: number;
+    /** Camera distance behind the subject. */
+    readonly distance: number;
+    /**
+     * Lateral camera offset. Non-zero only when `requireLowerSideFeatureVisibility` is set.
+     *
+     * Derived from the subject's own half-width so it scales with the asset instead of being tuned: a
+     * fixed offset that reveals a small car's wheels is far too small for a truck.
+     */
+    readonly sideOffset: number;
+    /**
+     * True when this framing can actually show the subject's lower side features.
+     *
+     * A caller must not claim wheels or feet are visible from a framing where this is false, however
+     * correct the grounding is.
+     */
+    readonly lowerSideFeaturesReadable: boolean;
+    /** Rendered subject measurements this framing was derived from. */
+    readonly subject: SubjectRenderedSize;
+    /** Predicted fraction of frame height the subject occupies at this distance. */
+    readonly predictedVerticalOccupancy: number;
+    /** World-space Y band, relative to the contact plane, that must stay readable. */
+    readonly lowerSilhouetteBand: readonly [number, number];
+    /** True when the predicted occupancy falls inside the requested range. */
+    readonly withinRequestedOccupancy: boolean;
+}
+/**
+ * Derive a chase camera from framing intent plus typed asset bounds.
+ *
+ * The distance is solved from the occupancy contract rather than tuned: at vertical FOV `f` and
+ * distance `d`, a subject of rendered height `h` occupies `h / (2 * d * tan(f/2))` of the frame.
+ * Solving for the midpoint of the requested occupancy range gives the distance directly, so a new
+ * asset with different proportions produces a different distance automatically and the route never
+ * restates a dimension.
+ */
+export declare function resolveChaseFraming(asset: SceneAssetLike, intent: ChaseFramingIntent): ChaseFraming;
+/** Bounds-level form of {@link resolveChaseFraming}, for fixtures and tests. */
+export declare function resolveChaseFramingFromBounds(bounds: SceneBounds, intent: ChaseFramingIntent): ChaseFraming;
+//# sourceMappingURL=SubjectFramingUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SubjectFramingUtils.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/SubjectFramingUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAElC,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,+DAA+D;IAC/D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,yFAAyF;IACzF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,mBAAmB,CAGjH;AAED,uFAAuF;AACvF,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,iBAAiB,GAAG,mBAAmB,CAgBzH;AAYD;;;;;GAKG;AACH,MAAM,WAAW,kBAAmB,SAAQ,iBAAiB;IAC3D,iFAAiF;IACjF,QAAQ,CAAC,wBAAwB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7D,yCAAyC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtD;;;;;;;;;OASG;IACH,QAAQ,CAAC,iCAAiC,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAClE;AAED,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,yBAAyB,EAAE,OAAO,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,gFAAgF;IAChF,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,0EAA0E;IAC1E,QAAQ,CAAC,wBAAwB,EAAE,OAAO,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAEnG;AAED,gFAAgF;AAChF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,GAAG,YAAY,CA+C3G"}

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

@@ -0,0 +1,126 @@
+/**
+ * Declarative subject framing derived from typed asset metadata.
+ *
+ * ## Why this exists
+ *
+ * Route code kept encoding *specific assets* into visual constants. Turbo's chase camera height was
+ * `0.46`, justified in a comment that recited one asset's bounds ("176.35 units tall over a 377.94
+ * longest axis"). Its `CAR_SCENE_HEIGHT` was worse: hardcoded to `2.209 / 6.958`, the bounds of a hero
+ * asset that had already been replaced twice, so every swap silently mis-seated the new car.
+ *
+ * The failure mode is structural, not careless. A number that is *correct* for one asset looks like a
+ * tuned design constant, so it survives review and survives asset swaps. The only durable fix is for
+ * routes to declare **intent** -- "frame a rear chase view where the subject occupies 25-40% of frame
+ * height and the lower silhouette stays visible" -- and let reusable code derive the numbers from the
+ * typed manifest.
+ *
+ * These helpers are pure and dependency-free so they can be unit tested against synthetic bounds and
+ * reused by any genre. They deliberately do **not** know about racing, platformers, or any route.
+ */
+import { boundsFromAsset, boundsHeight, boundsMaxDimension, boundsSize } from "./SceneGroundingUtils.js";
+/**
+ * Resolve what a subject actually measures once fit, straight from typed bounds.
+ *
+ * This replaces the `CAR_TARGET_MAX_DIMENSION * (BOUNDS_Y / BOUNDS_LONGEST)` arithmetic that routes
+ * were open-coding, and which is exactly where the stale-literal defect lived.
+ */
+export function resolveSubjectRenderedSize(asset, request) {
+    const bounds = boundsFromAsset(asset);
+    return resolveSubjectRenderedSizeFromBounds(bounds, request);
+}
+/** Bounds-level form of {@link resolveSubjectRenderedSize}, for fixtures and tests. */
+export function resolveSubjectRenderedSizeFromBounds(bounds, request) {
+    const rawSize = boundsSize(bounds);
+    const rawHeight = boundsHeight(bounds);
+    const rawMaxDimension = boundsMaxDimension(bounds);
+    const rawLength = Math.max(rawSize[0], rawSize[2]);
+    const fitScale = resolveSubjectFitScale({ height: rawHeight, maxDimension: rawMaxDimension, length: rawLength }, request);
+    return {
+        size: [rawSize[0] * fitScale, rawSize[1] * fitScale, rawSize[2] * fitScale],
+        height: rawHeight * fitScale,
+        maxDimension: rawMaxDimension * fitScale,
+        length: rawLength * fitScale,
+        fitScale
+    };
+}
+function resolveSubjectFitScale(raw, request) {
+    if (isPositive(request.targetHeight) && raw.height > 0)
+        return request.targetHeight / raw.height;
+    if (isPositive(request.targetLength) && raw.length > 0)
+        return request.targetLength / raw.length;
+    if (isPositive(request.targetMaxDimension) && raw.maxDimension > 0)
+        return request.targetMaxDimension / raw.maxDimension;
+    return 1;
+}
+/**
+ * Derive a chase camera from framing intent plus typed asset bounds.
+ *
+ * The distance is solved from the occupancy contract rather than tuned: at vertical FOV `f` and
+ * distance `d`, a subject of rendered height `h` occupies `h / (2 * d * tan(f/2))` of the frame.
+ * Solving for the midpoint of the requested occupancy range gives the distance directly, so a new
+ * asset with different proportions produces a different distance automatically and the route never
+ * restates a dimension.
+ */
+export function resolveChaseFraming(asset, intent) {
+    return resolveChaseFramingFromBounds(boundsFromAsset(asset), intent);
+}
+/** Bounds-level form of {@link resolveChaseFraming}, for fixtures and tests. */
+export function resolveChaseFramingFromBounds(bounds, intent) {
+    const subject = resolveSubjectRenderedSizeFromBounds(bounds, intent);
+    const [minOccupancy, maxOccupancy] = normalizeOccupancy(intent.subjectVerticalOccupancy);
+    const targetOccupancy = (minOccupancy + maxOccupancy) / 2;
+    const fovRadians = clamp(intent.fov, 1, 170) * Math.PI / 180;
+    const halfFovTangent = Math.tan(fovRadians / 2);
+    // Solve d from occupancy = height / (2 * d * tan(fov/2)).
+    const distance = subject.height > 0 && targetOccupancy > 0 && halfFovTangent > 0
+        ? subject.height / (2 * targetOccupancy * halfFovTangent)
+        : Math.max(subject.maxDimension, 0.001) * 2;
+    const eyeHeightFraction = intent.eyeHeightFraction ?? 0.9;
+    const height = subject.height * eyeHeightFraction;
+    const lowerFraction = clamp(intent.lowerSilhouetteFraction ?? 0.3, 0, 1);
+    const predictedVerticalOccupancy = distance > 0 && halfFovTangent > 0
+        ? subject.height / (2 * distance * halfFovTangent)
+        : 0;
+    /*
+     * Lateral offset needed to bring the subject's flank into view.
+     *
+     * At offset `s` and distance `d` the view direction is rotated by `atan(s/d)` off-axis. Bringing a
+     * flank into view needs enough rotation that the near-side lower body is no longer occluded by the
+     * subject's own width; `0.45 * halfWidth / distance`-scaled offset yields roughly 12-20 degrees for
+     * typical chase distances, which is the range where a car's near wheels read without the frame
+     * becoming a side-on beauty shot.
+     */
+    // The *narrower* horizontal axis is the subject's width; the wider one is its length. A chase camera
+    // steps sideways relative to width, so using the longest axis here would overshoot badly on a long car.
+    const halfWidth = Math.min(subject.size[0], subject.size[2]) / 2;
+    const sideOffset = intent.requireLowerSideFeatureVisibility ? halfWidth * 3.2 : 0;
+    const offAxisRadians = distance > 0 ? Math.atan(sideOffset / distance) : 0;
+    return {
+        height: round4(height),
+        distance: round4(distance),
+        sideOffset: round4(sideOffset),
+        // Below ~8 degrees off-axis the subject's own body still hides its lower flank.
+        lowerSideFeaturesReadable: offAxisRadians >= 0.14,
+        subject,
+        predictedVerticalOccupancy: round4(predictedVerticalOccupancy),
+        lowerSilhouetteBand: [0, round4(subject.height * lowerFraction)],
+        withinRequestedOccupancy: predictedVerticalOccupancy >= minOccupancy - 1e-6 &&
+            predictedVerticalOccupancy <= maxOccupancy + 1e-6
+    };
+}
+function normalizeOccupancy(range) {
+    const low = Math.min(range[0], range[1]);
+    const high = Math.max(range[0], range[1]);
+    return [clamp(low, 0.001, 1), clamp(high, 0.001, 1)];
+}
+function clamp(value, low, high) {
+    return Math.min(high, Math.max(low, value));
+}
+function round4(value) {
+    const rounded = Math.round(value * 10_000) / 10_000;
+    return rounded === 0 ? 0 : rounded;
+}
+function isPositive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+//# sourceMappingURL=SubjectFramingUtils.js.map

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

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

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

@@ -0,0 +1,81 @@
+/**
+ * Reusable touch/pointer bindings for on-screen game controls.
+ *
+ * ## Why this is in the reusable layer
+ *
+ * The replicability metric's repeated-cluster detector (added in defect 113) found this code duplicated
+ * **byte-for-byte** between Skyline Runner and Turbo Drift Circuit: a `bindHoldControl` that translates
+ * pointer press/release into synthetic keyboard events, plus a `pulseKey` for momentary buttons. Two routes
+ * had independently authored the same 13 lines, and a third would have copied them again.
+ *
+ * That is precisely the duplication the brief asks the metric to surface and the reusable layer to absorb.
+ * Every public game route needs on-screen controls -- the route-primary probe gates
+ * `interactive-controls-outside-viewport` -- so this is genre-independent infrastructure, not art direction.
+ *
+ * ## Why synthetic keyboard events rather than a direct input API
+ *
+ * The routes already own a keyboard action map (`game.input({ actions: ... })`) that is the single source of
+ * truth for what a key does. Dispatching real `KeyboardEvent`s means a touch press and a physical key press
+ * travel the *same* path, so the gameplay proof that keyboard input changes state also covers the buttons.
+ * A parallel input path would need its own proof and could drift from the keyboard behaviour.
+ *
+ * Bindings are additive and idempotent per element: re-binding the same id replaces its listeners rather than
+ * stacking them, because a route that re-runs setup after a reset would otherwise fire one keydown per bind.
+ */
+/** A control that holds its key down while pressed, e.g. throttle or move-left. */
+export interface HoldControlBinding {
+    /** DOM id of the button element. Missing elements are skipped, not thrown on. */
+    readonly elementId: string;
+    /** `KeyboardEvent.code` to synthesise, e.g. `"KeyA"`. */
+    readonly code: string;
+}
+/** A control that fires one press-and-release, e.g. jump or reset. */
+export interface PulseControlBinding extends HoldControlBinding {
+    /** Milliseconds the synthetic key stays down. Defaults to 40ms. */
+    readonly holdMs?: number | undefined;
+}
+/**
+ * Minimal DOM surface this module needs.
+ *
+ * Declared structurally so the module is testable without a DOM environment. This repository runs its unit
+ * suite in plain Node with no `jsdom`, which is a deliberate convention: browser behaviour is proven in
+ * Playwright against a real browser, not against a DOM emulator. Accepting an injectable host keeps the
+ * *binding logic* -- press/release pairing, idempotence, teardown -- under fast unit coverage without
+ * pretending a shim is a browser.
+ */
+export interface TouchControlHost {
+    getElementById(id: string): TouchControlElement | null;
+    dispatchKey(code: string, type: "keydown" | "keyup"): void;
+    setTimer(callback: () => void, delayMs: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+/** The element operations a control binding performs. */
+export interface TouchControlElement {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface GameControlBindingSpec {
+    readonly hold?: readonly HoldControlBinding[] | undefined;
+    readonly pulse?: readonly PulseControlBinding[] | undefined;
+    /**
+     * Override the DOM/timer host. Defaults to `window`/`document`, so routes pass nothing.
+     * Exists for unit coverage of the binding logic; see `TouchControlHost`.
+     */
+    readonly host?: TouchControlHost | undefined;
+}
+export interface GameControlBindingResult {
+    /** Element ids that were found and bound. */
+    readonly bound: readonly string[];
+    /** Element ids named in the spec but absent from the DOM, so a typo is visible rather than silent. */
+    readonly missing: readonly string[];
+    /** Remove every listener this call attached. */
+    dispose(): void;
+}
+/**
+ * Bind on-screen controls to synthetic keyboard events.
+ *
+ * Returns which ids were bound and which were missing, so a route can assert its own control contract
+ * instead of discovering a typo through a failing probe.
+ */
+export declare function bindGameTouchControls(spec: GameControlBindingSpec): GameControlBindingResult;
+//# sourceMappingURL=TouchControlBinding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TouchControlBinding.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/TouchControlBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IACvD,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACzD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,gDAAgD;IAChD,OAAO,IAAI,IAAI,CAAC;CACjB;AAeD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAyE5F"}

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

@@ -0,0 +1,116 @@
+/**
+ * Reusable touch/pointer bindings for on-screen game controls.
+ *
+ * ## Why this is in the reusable layer
+ *
+ * The replicability metric's repeated-cluster detector (added in defect 113) found this code duplicated
+ * **byte-for-byte** between Skyline Runner and Turbo Drift Circuit: a `bindHoldControl` that translates
+ * pointer press/release into synthetic keyboard events, plus a `pulseKey` for momentary buttons. Two routes
+ * had independently authored the same 13 lines, and a third would have copied them again.
+ *
+ * That is precisely the duplication the brief asks the metric to surface and the reusable layer to absorb.
+ * Every public game route needs on-screen controls -- the route-primary probe gates
+ * `interactive-controls-outside-viewport` -- so this is genre-independent infrastructure, not art direction.
+ *
+ * ## Why synthetic keyboard events rather than a direct input API
+ *
+ * The routes already own a keyboard action map (`game.input({ actions: ... })`) that is the single source of
+ * truth for what a key does. Dispatching real `KeyboardEvent`s means a touch press and a physical key press
+ * travel the *same* path, so the gameplay proof that keyboard input changes state also covers the buttons.
+ * A parallel input path would need its own proof and could drift from the keyboard behaviour.
+ *
+ * Bindings are additive and idempotent per element: re-binding the same id replaces its listeners rather than
+ * stacking them, because a route that re-runs setup after a reset would otherwise fire one keydown per bind.
+ */
+/** Tracks attached listeners per element id so a re-bind replaces rather than stacks. */
+const attached = new Map();
+/** The real browser host: synthetic keyboard events on `window`, elements from `document`. */
+function browserHost() {
+    return {
+        getElementById: (id) => (typeof document === "undefined" ? null : document.getElementById(id)),
+        dispatchKey: (code, type) => window.dispatchEvent(new KeyboardEvent(type, { code, bubbles: true })),
+        setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+        clearTimer: (handle) => clearTimeout(handle)
+    };
+}
+/**
+ * Bind on-screen controls to synthetic keyboard events.
+ *
+ * Returns which ids were bound and which were missing, so a route can assert its own control contract
+ * instead of discovering a typo through a failing probe.
+ */
+export function bindGameTouchControls(spec) {
+    const host = spec.host ?? browserHost();
+    const bound = [];
+    const missing = [];
+    const teardown = [];
+    const claim = (elementId) => {
+        const element = host.getElementById(elementId);
+        if (!element) {
+            missing.push(elementId);
+            return undefined;
+        }
+        // Replace any previous binding for this id; see the note on idempotence above.
+        attached.get(elementId)?.();
+        bound.push(elementId);
+        return element;
+    };
+    for (const control of spec.hold ?? []) {
+        const element = claim(control.elementId);
+        if (!element)
+            continue;
+        const press = () => host.dispatchKey(control.code, "keydown");
+        const release = () => host.dispatchKey(control.code, "keyup");
+        element.addEventListener("pointerdown", press);
+        element.addEventListener("pointerup", release);
+        // `pointercancel` and `pointerleave` both matter: a finger sliding off a button must not latch the key on.
+        element.addEventListener("pointercancel", release);
+        element.addEventListener("pointerleave", release);
+        const remove = () => {
+            element.removeEventListener("pointerdown", press);
+            element.removeEventListener("pointerup", release);
+            element.removeEventListener("pointercancel", release);
+            element.removeEventListener("pointerleave", release);
+            // Release on teardown, so disposing mid-press cannot leave the key stuck down.
+            release();
+            attached.delete(control.elementId);
+        };
+        attached.set(control.elementId, remove);
+        teardown.push(remove);
+    }
+    for (const control of spec.pulse ?? []) {
+        const element = claim(control.elementId);
+        if (!element)
+            continue;
+        const holdMs = Math.max(1, control.holdMs ?? 40);
+        const timers = new Set();
+        const press = () => {
+            host.dispatchKey(control.code, "keydown");
+            const timer = host.setTimer(() => {
+                timers.delete(timer);
+                host.dispatchKey(control.code, "keyup");
+            }, holdMs);
+            timers.add(timer);
+        };
+        element.addEventListener("click", press);
+        const remove = () => {
+            element.removeEventListener("click", press);
+            // Clear pending release timers, or a disposed control can still dispatch after teardown.
+            for (const timer of timers)
+                host.clearTimer(timer);
+            timers.clear();
+            attached.delete(control.elementId);
+        };
+        attached.set(control.elementId, remove);
+        teardown.push(remove);
+    }
+    return {
+        bound,
+        missing,
+        dispose: () => {
+            for (const remove of teardown)
+                remove();
+        }
+    };
+}
+//# sourceMappingURL=TouchControlBinding.js.map

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

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

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

@@ -33,6 +33,9 @@ export * from "./CloudRenderAdapter.js";
 export * from "./BatchEpisodeRenderer.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
+export * from "./SubjectFramingUtils.js";
+export * from "./LayeredSceneComposition.js";
+export * from "./TouchControlBinding.js";
 export * from "./AssetLibraryBrowser.js";
 export * from "./DialogueAlignment.js";
 export * from "./PerformancePoseEditor.js";
@@ -104,6 +107,9 @@ export * from "./AnimationPerformance.js";
 export * from "./AnimationRenderQueue.js";
 export * from "./AnimationAssetManifest.js";
 export * from "./SceneGroundingUtils.js";
+export * from "./SubjectFramingUtils.js";
+export * from "./LayeredSceneComposition.js";
+export * from "./TouchControlBinding.js";
 export * from "./AssetLibraryBrowser.js";
 export type AuraVec3 = readonly [number, number, number];
 export type AuraColor = `#${string}` | string;
@@ -607,7 +613,18 @@ export interface AuraRendererDiagnosticReport {
         readonly antiBlowout: boolean;
     };
     readonly shadows: {
+        /** True only when a mounted runtime actually sampled a shadow map. */
         readonly enabled: boolean;
+        /** The scene asked for shadows: a shadow-casting light was collected. */
+        readonly requested: boolean;
+        /** A shadow depth target was allocated and rendered by the device. */
+        readonly mapRendered: boolean;
+        /** A shader actually bound and sampled the shadow map. */
+        readonly mapSampled: boolean;
+        readonly mapSize?: number;
+        readonly label?: string;
+        readonly nativeShadowMapBindings: number;
+        readonly shadowRenderTargetsAllocated: number;
         readonly contactShadows: number;
         readonly mapType: "pcf-soft";
     };
@@ -1618,6 +1635,7 @@ export interface AuraPlatformerPresentationSurfaceOptions {
     readonly guideVisibility?: "public" | "evidence" | "full";
     readonly platformColor?: AuraColor;
     readonly platformTrimColor?: AuraColor;
+    readonly checkpointColor?: AuraColor;
     readonly hazardColor?: AuraColor;
     readonly collectibleColor?: AuraColor;
     readonly finishColor?: AuraColor;
@@ -2469,4 +2487,25 @@ export declare const performance: {
 };
 export declare function captureAuraScreenshot(target?: HTMLCanvasElement): AuraScreenshot;
 export declare function createAuraAssetLoadError(asset: AuraAssetRef<"model">, reason: string): AuraRuntimeError;
+interface ProductionBoundsProbe {
+    readonly assetId: string;
+    readonly metadata: {
+        readonly min: readonly number[];
+        readonly max: readonly number[];
+    };
+    readonly loaded: {
+        readonly min: readonly number[];
+        readonly max: readonly number[];
+    };
+}
+/**
+ * Diagnostic: manifest `boundsMetadata` versus the bounds actually computed from the
+ * loaded GLB, per typed asset routed through the production bridge.
+ *
+ * The bridge sizes models from loaded bounds because those are what the geometry
+ * really occupies. This accessor exists so a disagreement with manifest metadata —
+ * which `camera.frameAsset` must use, being synchronous — is observable instead of
+ * silently producing mismatched framing.
+ */
+export declare function auraProductionBoundsProbes(): readonly ProductionBoundsProbe[];
 //# sourceMappingURL=index.d.ts.map