@aura3d/engine 1.4.5 → 1.5.1

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

@@ -0,0 +1,331 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function projectWorldPoint(viewProjection, point) {
+    const m = viewProjection;
+    const [x, y, z] = point;
+    // Column-major: element (row r, col c) is m[c * 4 + r], matching the matrices
+    // produced by `multiply4`/`perspective` in the agent API renderer.
+    const cx = m[0] * x + m[4] * y + m[8] * z + m[12];
+    const cy = m[1] * x + m[5] * y + m[9] * z + m[13];
+    const cz = m[2] * x + m[6] * y + m[10] * z + m[14];
+    const cw = m[3] * x + m[7] * y + m[11] * z + m[15];
+    if (cw === 0)
+        return { ndc: [0, 0, 0], w: 0 };
+    return { ndc: [cx / cw, cy / cw, cz / cw], w: cw };
+}
+/** Convert NDC to CSS-pixel screen coordinates for a viewport. */
+export function ndcToScreen(ndc, viewport) {
+    return [
+        (ndc[0] * 0.5 + 0.5) * viewport.width,
+        (1 - (ndc[1] * 0.5 + 0.5)) * viewport.height
+    ];
+}
+const SCREEN_ANCHOR_MARGIN = 14;
+/**
+ * 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 function projectWorldLabels(labels, viewProjection, viewport) {
+    const compactScale = viewport.compact === true ? 0.86 : 1;
+    return labels.map((label) => {
+        const fontSize = Math.max(11, Math.round((label.fontSize ?? 14) * compactScale));
+        const color = label.color ?? "#f8fafc";
+        const background = label.background ?? "rgba(17,24,39,0.88)";
+        const leader = label.leader ?? false;
+        if (label.screenAnchor) {
+            const [x, y] = screenAnchorPosition(label.screenAnchor, viewport, fontSize);
+            return {
+                id: label.id,
+                text: label.text,
+                x,
+                y,
+                anchorX: x,
+                anchorY: y,
+                visible: true,
+                clamped: false,
+                behindCamera: false,
+                fontSize,
+                color,
+                background,
+                leader: false,
+                depth: 0
+            };
+        }
+        const projected = projectWorldPoint(viewProjection, label.anchor);
+        const behindCamera = projected.w <= 0;
+        const [boxAnchorX, boxAnchorY] = ndcToScreen(projected.ndc, viewport);
+        // The leader endpoint is projected separately so it lands on the subject, not
+        // on the label. Falls back to the label's own anchor when none is given.
+        const leaderTarget = label.leaderAnchor
+            ? ndcToScreen(projectWorldPoint(viewProjection, label.leaderAnchor).ndc, viewport)
+            : [boxAnchorX, boxAnchorY];
+        const anchorX = leaderTarget[0];
+        const anchorY = leaderTarget[1];
+        const offset = label.screenOffset ?? [0, -28];
+        let x = boxAnchorX + offset[0] * compactScale;
+        let y = boxAnchorY + offset[1] * compactScale;
+        const policy = label.offscreenPolicy ?? "clamp";
+        const hideBehind = label.hideWhenBehindCamera ?? true;
+        // Estimated half-width from character count: the exact box is measured by the
+        // DOM, but clamping needs a bound before layout.
+        const halfWidth = Math.max(24, label.text.length * fontSize * 0.31);
+        const halfHeight = fontSize * 0.9;
+        const withinViewport = x >= -halfWidth && x <= viewport.width + halfWidth
+            && y >= -halfHeight && y <= viewport.height + halfHeight;
+        let clamped = false;
+        let visible = true;
+        if (behindCamera && hideBehind) {
+            visible = false;
+        }
+        else if (!withinViewport) {
+            if (policy === "hide") {
+                visible = false;
+            }
+            else if (policy === "clamp") {
+                const clampedX = Math.min(Math.max(x, halfWidth + SCREEN_ANCHOR_MARGIN), viewport.width - halfWidth - SCREEN_ANCHOR_MARGIN);
+                const clampedY = Math.min(Math.max(y, halfHeight + SCREEN_ANCHOR_MARGIN), viewport.height - halfHeight - SCREEN_ANCHOR_MARGIN);
+                clamped = clampedX !== x || clampedY !== y;
+                x = clampedX;
+                y = clampedY;
+            }
+        }
+        return {
+            id: label.id,
+            text: label.text,
+            x: round(x),
+            y: round(y),
+            anchorX: round(anchorX),
+            anchorY: round(anchorY),
+            visible,
+            clamped,
+            behindCamera,
+            fontSize,
+            color,
+            background,
+            leader,
+            depth: round(projected.ndc[2])
+        };
+    });
+}
+/**
+ * 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 function resolveLabelCollisions(labels, options = {}) {
+    const minGap = options.minGap ?? 4;
+    const ordered = [...labels].sort((a, b) => a.depth - b.depth);
+    const placed = [];
+    for (const label of ordered) {
+        if (!label.visible) {
+            placed.push(label);
+            continue;
+        }
+        let y = label.y;
+        const halfHeight = label.fontSize * 0.9;
+        const halfWidth = Math.max(24, label.text.length * label.fontSize * 0.31);
+        let moved = true;
+        let guard = 0;
+        while (moved && guard < 32) {
+            moved = false;
+            guard += 1;
+            for (const other of placed) {
+                if (!other.visible)
+                    continue;
+                const otherHalfHeight = other.fontSize * 0.9;
+                const otherHalfWidth = Math.max(24, other.text.length * other.fontSize * 0.31);
+                const overlapsX = Math.abs(label.x - other.x) < halfWidth + otherHalfWidth;
+                const overlapsY = Math.abs(y - other.y) < halfHeight + otherHalfHeight + minGap;
+                if (overlapsX && overlapsY) {
+                    y = other.y - (otherHalfHeight + halfHeight + minGap);
+                    moved = true;
+                }
+            }
+        }
+        placed.push(y === label.y ? label : { ...label, y: round(y) });
+    }
+    // Restore the caller's ordering so ids stay stable for tests and evidence.
+    const byId = new Map(placed.map((label) => [label.id, label]));
+    return labels.map((label) => byId.get(label.id) ?? label);
+}
+/**
+ * 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 function createWorldLabelLayer(host) {
+    const root = document.createElement("div");
+    root.className = "aura-world-label-layer";
+    root.setAttribute("data-aura-world-labels", "");
+    root.style.cssText = [
+        "position:absolute",
+        "inset:0",
+        "overflow:hidden",
+        "pointer-events:none",
+        "z-index:6"
+    ].join(";");
+    const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    svg.setAttribute("width", "100%");
+    svg.setAttribute("height", "100%");
+    svg.style.cssText = "position:absolute;inset:0;overflow:visible";
+    root.append(svg);
+    const parentStyle = getComputedStyle(host.container);
+    if (parentStyle.position === "static")
+        host.container.style.position = "relative";
+    host.container.append(root);
+    let labels = [];
+    let projected = [];
+    const elements = new Map();
+    const leaders = new Map();
+    const viewport = () => {
+        const rect = host.canvas.getBoundingClientRect();
+        const width = rect.width || host.canvas.clientWidth || host.canvas.width;
+        const height = rect.height || host.canvas.clientHeight || host.canvas.height;
+        return { width, height, compact: width < 560 };
+    };
+    const ensureElement = (label) => {
+        let element = elements.get(label.id);
+        if (!element) {
+            element = document.createElement("div");
+            element.className = "aura-world-label";
+            element.setAttribute("role", "note");
+            element.setAttribute("data-aura-label-id", label.id);
+            element.style.cssText = [
+                "position:absolute",
+                "transform:translate(-50%,-50%)",
+                "white-space:nowrap",
+                "border-radius:6px",
+                "padding:4px 8px",
+                "font:600 14px/1.2 system-ui,-apple-system,BlinkMacSystemFont,sans-serif",
+                "border:1px solid rgba(148,163,184,0.5)",
+                "pointer-events:none"
+            ].join(";");
+            root.append(element);
+            elements.set(label.id, element);
+        }
+        return element;
+    };
+    const ensureLeader = (id) => {
+        let line = leaders.get(id);
+        if (!line) {
+            line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+            line.setAttribute("stroke-width", "1.2");
+            line.setAttribute("stroke-linecap", "round");
+            svg.append(line);
+            leaders.set(id, line);
+        }
+        return line;
+    };
+    const draw = () => {
+        const seen = new Set();
+        for (const label of projected) {
+            seen.add(label.id);
+            const element = ensureElement(label);
+            if (!label.visible) {
+                element.style.display = "none";
+                leaders.get(label.id)?.setAttribute("stroke", "transparent");
+                continue;
+            }
+            element.style.display = "block";
+            element.style.left = `${label.x}px`;
+            element.style.top = `${label.y}px`;
+            element.style.color = label.color;
+            element.style.background = label.background;
+            element.style.fontSize = `${label.fontSize}px`;
+            if (element.textContent !== label.text)
+                element.textContent = label.text;
+            if (label.leader) {
+                const line = ensureLeader(label.id);
+                line.setAttribute("x1", String(label.x));
+                line.setAttribute("y1", String(label.y));
+                line.setAttribute("x2", String(label.anchorX));
+                line.setAttribute("y2", String(label.anchorY));
+                line.setAttribute("stroke", label.color);
+                line.setAttribute("stroke-opacity", "0.72");
+            }
+            else {
+                leaders.get(label.id)?.setAttribute("stroke", "transparent");
+            }
+        }
+        // Clean up labels whose target was removed.
+        for (const [id, element] of elements) {
+            if (seen.has(id))
+                continue;
+            element.remove();
+            elements.delete(id);
+            leaders.get(id)?.remove();
+            leaders.delete(id);
+        }
+    };
+    return {
+        setLabels(next) {
+            labels = next;
+        },
+        update(viewProjection) {
+            projected = resolveLabelCollisions(projectWorldLabels(labels, viewProjection, viewport()));
+            draw();
+        },
+        snapshot() {
+            return projected;
+        },
+        dispose() {
+            for (const element of elements.values())
+                element.remove();
+            elements.clear();
+            for (const line of leaders.values())
+                line.remove();
+            leaders.clear();
+            root.remove();
+        }
+    };
+}
+function screenAnchorPosition(anchor, viewport, fontSize) {
+    const margin = SCREEN_ANCHOR_MARGIN + fontSize;
+    if (anchor === "top-left")
+        return [margin * 2.4, margin];
+    if (anchor === "top-right")
+        return [viewport.width - margin * 2.4, margin];
+    if (anchor === "bottom-left")
+        return [margin * 2.4, viewport.height - margin];
+    return [viewport.width - margin * 2.4, viewport.height - margin];
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=WorldLabelRenderer.js.map

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

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

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

@@ -1,4 +1,14 @@
 import { type Collider, type ColliderDescriptor, type CollisionEvent, type Constraint, type ConstraintDescriptor, type Contact, type DebugLine, type PhysicsBackendSelection, type PhysicsShape, type PhysicsSnapshot, type PhysicsWorldDescriptor, type RaycastHit, type RaycastOptions, type RigidBody, type RigidBodyDescriptor, type RigidBodyType, type ScenePhysicsNode, type SphereCastHit } from "@aura3d/physics";
+import { type ProjectedLabel } from "./WorldLabelRenderer.js";
+export * from "./SpatialAnchoring.js";
+export * from "./FocusSelection.js";
+export * from "./WorldLabelRenderer.js";
+export * from "./VehicleChassis.js";
+export * from "./VehicleDriverAi.js";
+export * from "./PlatformerMotion.js";
+export * from "./CombatFrameData.js";
+export * from "./SceneQueries.js";
+export * from "./ApplicationKits.js";
 export * from "./FrameEncoder.js";
 export * from "./BrowserFrameCaptureAdapter.js";
 export * from "./MediaRecorderFrameEncoder.js";
@@ -33,6 +43,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 +117,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;
@@ -515,6 +531,17 @@ export interface AuraLabelNode extends AuraTransformSpec {
     readonly name?: string;
     readonly text: string;
     readonly target?: string;
+    /**
+     * World point the label is attached to.
+     *
+     * `position` is where the label box sits; `anchorWorldPosition` is what a
+     * leader line points at. When omitted the label anchors to its own position.
+     * Both are projected every frame by the world-label layer, so a label tracks
+     * its subject as the camera moves.
+     */
+    readonly anchorWorldPosition?: AuraVec3;
+    /** Behaviour when the anchor projects outside the viewport. Defaults to "clamp". */
+    readonly offscreenPolicy?: "hide" | "clamp" | "draw";
     readonly color?: AuraColor;
     readonly background?: AuraColor;
     readonly size?: number;
@@ -607,7 +634,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 +1656,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;
@@ -2215,6 +2254,15 @@ export interface AuraDiagnostics {
     readonly renderer?: AuraRendererDiagnosticReport;
     readonly warnings: readonly string[];
     readonly errors: readonly string[];
+    /**
+     * Labels the world-label layer actually placed on screen this frame, with their
+     * projected pixel positions and visibility.
+     *
+     * This distinguishes "a label node exists in the scene" from "a label is drawn
+     * where the user can read it". Every production callout was silently dropped
+     * while evidence counted the nodes, so the counted-node signal is not enough.
+     */
+    readonly labels?: readonly ProjectedLabel[];
 }
 export interface AuraAssetProvenance {
     readonly source: "typed-aura-assets-manifest" | "unsafe-url" | "inline-definition";
@@ -2469,4 +2517,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