@aura3d/engine 1.5.0 → 1.5.2

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA0EH;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,cAAiC,EACjC,KAAgB;IAEhB,MAAM,CAAC,GAAG,cAAc,CAAC;IACzB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;IACxB,8EAA8E;IAC9E,mEAAmE;IACnE,MAAM,EAAE,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,CAAC;IAClG,MAAM,EAAE,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,CAAC;IAClG,MAAM,EAAE,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,CAAC;IACnG,MAAM,EAAE,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,CAAC,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,GAAG,CAAC,GAAI,CAAC,CAAC,EAAE,CAAY,CAAC;IACnG,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC9C,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;AACrD,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,WAAW,CAAC,GAAsC,EAAE,QAAuB;IACzF,OAAO;QACL,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK;QACrC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM;KAC7C,CAAC;AACJ,CAAC;AAED,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA6B,EAC7B,cAAiC,EACjC,QAAuB;IAEvB,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC;QACjF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC;QACvC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,qBAAqB,CAAC;QAC7D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC;QAErC,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;YACvB,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC5E,OAAO;gBACL,EAAE,EAAE,KAAK,CAAC,EAAE;gBACZ,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,CAAC;gBACD,CAAC;gBACD,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,KAAK;gBACnB,QAAQ;gBACR,KAAK;gBACL,UAAU;gBACV,MAAM,EAAE,KAAK;gBACb,KAAK,EAAE,CAAC;aACT,CAAC;QACJ,CAAC;QAED,MAAM,SAAS,GAAG,iBAAiB,CAAC,cAAc,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAClE,MAAM,YAAY,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,WAAW,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACtE,8EAA8E;QAC9E,yEAAyE;QACzE,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY;YACrC,CAAC,CAAC,WAAW,CAAC,iBAAiB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC;YAClF,CAAC,CAAE,CAAC,UAAU,EAAE,UAAU,CAAW,CAAC;QACxC,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC;QAC9C,IAAI,CAAC,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC;QAE9C,MAAM,MAAM,GAAG,KAAK,CAAC,eAAe,IAAI,OAAO,CAAC;QAChD,MAAM,UAAU,GAAG,KAAK,CAAC,oBAAoB,IAAI,IAAI,CAAC;QACtD,8EAA8E;QAC9E,iDAAiD;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,QAAQ,GAAG,GAAG,CAAC;QAClC,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,QAAQ,CAAC,KAAK,GAAG,SAAS;eACpE,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC;QAE3D,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,OAAO,GAAG,IAAI,CAAC;QACnB,IAAI,YAAY,IAAI,UAAU,EAAE,CAAC;YAC/B,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,IAAI,CAAC,cAAc,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;iBAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,oBAAoB,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,GAAG,oBAAoB,CAAC,CAAC;gBAC5H,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,GAAG,UAAU,GAAG,oBAAoB,CAAC,CAAC;gBAC/H,OAAO,GAAG,QAAQ,KAAK,CAAC,IAAI,QAAQ,KAAK,CAAC,CAAC;gBAC3C,CAAC,GAAG,QAAQ,CAAC;gBACb,CAAC,GAAG,QAAQ,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO;YACL,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YACX,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YACX,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;YACvB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC;YACvB,OAAO;YACP,OAAO;YACP,YAAY;YACZ,QAAQ;YACR,KAAK;YACL,UAAU;YACV,MAAM;YACN,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SAC/B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAiC,EACjC,UAAoD,EAAE;IAEtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAqB,EAAE,CAAC;IACpC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;QAChB,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC;QACxC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;QAC1E,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,OAAO,KAAK,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;YAC3B,KAAK,GAAG,KAAK,CAAC;YACd,KAAK,IAAI,CAAC,CAAC;YACX,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,OAAO;oBAAE,SAAS;gBAC7B,MAAM,eAAe,GAAG,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC;gBAC7C,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;gBAC/E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,cAAc,CAAC;gBAC3E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,eAAe,GAAG,MAAM,CAAC;gBAChF,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;oBAC3B,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,eAAe,GAAG,UAAU,GAAG,MAAM,CAAC,CAAC;oBACtD,KAAK,GAAG,IAAI,CAAC;gBACf,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,2EAA2E;IAC3E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,CAAC;AAC5D,CAAC;AAmBD;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAyB;IAC7D,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,SAAS,GAAG,wBAAwB,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG;QACnB,mBAAmB;QACnB,SAAS;QACT,iBAAiB;QACjB,qBAAqB;QACrB,WAAW;KACZ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,MAAM,GAAG,GAAG,QAAQ,CAAC,eAAe,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;IAC1E,GAAG,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACnC,GAAG,CAAC,KAAK,CAAC,OAAO,GAAG,4CAA4C,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEjB,MAAM,WAAW,GAAG,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,WAAW,CAAC,QAAQ,KAAK,QAAQ;QAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC;IAClF,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE5B,IAAI,MAAM,GAA0B,EAAE,CAAC;IACvC,IAAI,SAAS,GAA8B,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAElD,MAAM,QAAQ,GAAG,GAAkB,EAAE;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QACzE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC;IACjD,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,KAAqB,EAAe,EAAE;QAC3D,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YACxC,OAAO,CAAC,SAAS,GAAG,kBAAkB,CAAC;YACvC,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;YACrD,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG;gBACtB,mBAAmB;gBACnB,gCAAgC;gBAChC,oBAAoB;gBACpB,mBAAmB;gBACnB,iBAAiB;gBACjB,yEAAyE;gBACzE,wCAAwC;gBACxC,qBAAqB;aACtB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACZ,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACrB,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,EAAU,EAAkB,EAAE;QAClD,IAAI,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAC,4BAA4B,EAAE,MAAM,CAAC,CAAC;YACtE,IAAI,CAAC,YAAY,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;YACzC,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;YAC7C,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACnB,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;gBAC7D,SAAS;YACX,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC;YACpC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC;YAC/C,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,IAAI;gBAAE,OAAO,CAAC,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC;YACzE,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjB,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACpC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC/C,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC/C,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;gBACzC,IAAI,CAAC,YAAY,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QACD,4CAA4C;QAC5C,KAAK,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,QAAQ,EAAE,CAAC;YACrC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC3B,OAAO,CAAC,MAAM,EAAE,CAAC;YACjB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACpB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;YAC1B,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,SAAS,CAAC,IAAI;YACZ,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,CAAC,cAAc;YACnB,SAAS,GAAG,sBAAsB,CAAC,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC3F,IAAI,EAAE,CAAC;QACT,CAAC;QACD,QAAQ;YACN,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO;YACL,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE;gBAAE,OAAO,CAAC,MAAM,EAAE,CAAC;YAC1D,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,IAAI,CAAC,MAAM,EAAE,CAAC;YACnD,OAAO,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAA+C,EAC/C,QAAuB,EACvB,QAAgB;IAEhB,MAAM,MAAM,GAAG,oBAAoB,GAAG,QAAQ,CAAC;IAC/C,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC;IACzD,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,GAAG,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC,CAAC;IAC3E,IAAI,MAAM,KAAK,aAAa;QAAE,OAAO,CAAC,MAAM,GAAG,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9E,OAAO,CAAC,QAAQ,CAAC,KAAK,GAAG,MAAM,GAAG,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AACnE,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/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";
@@ -521,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;
@@ -887,7 +908,7 @@ export declare const lights: {
         readonly intensity?: number;
     }) => AuraNodeBuilder<AuraLightNode>;
 };
-export type AuraCameraMode = "perspective" | "orbit" | "dolly" | "follow" | "path" | "flythrough";
+export type AuraCameraMode = "perspective" | "orbit" | "dolly" | "follow" | "path" | "flythrough" | "orthographic" | "isometric";
 export interface AuraCameraSpec {
     readonly mode: AuraCameraMode;
     readonly position?: AuraVec3;
@@ -905,6 +926,16 @@ export interface AuraCameraSpec {
     readonly captureTime?: number;
     readonly smoothing?: number;
     readonly subjectEmphasis?: number;
+    /**
+     * Half-height of the orthographic frustum, in world units.
+     *
+     * Orthographic projection has no field of view, so this is what sets image
+     * scale: the camera sees `orthographicSize` units above and below its target
+     * regardless of how far away it sits. Horizontal extent follows from the
+     * viewport aspect, which keeps the image square-on rather than stretched.
+     * Ignored by every perspective mode.
+     */
+    readonly orthographicSize?: number;
 }
 export interface AuraBoundsSpec {
     readonly min: AuraVec3;
@@ -941,6 +972,28 @@ export declare const camera: {
         readonly from?: AuraVec3;
         readonly to?: AuraVec3;
     }) => AuraCameraSpec;
+    /**
+     * A parallel-projection camera: no foreshortening, so equal world lengths
+     * occupy equal screen lengths wherever they sit in depth.
+     *
+     * Reach for this when the projection is part of the meaning rather than a
+     * stylistic choice — CAD and engineering views, floor plans, technical
+     * diagrams, sprite and texture bakes, chart axes, and product shots that must
+     * read as measurable. A long-lens perspective camera approximates it but
+     * still converges, which is visible on long straight edges.
+     */
+    readonly orthographic: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
+    /**
+     * The conventional isometric view: an orthographic camera on a 45-degree
+     * azimuth and a ~35.264-degree elevation.
+     *
+     * That elevation is `atan(1 / sqrt(2))`, the angle at which the three world
+     * axes project to equal screen lengths and 120 degrees apart. Authoring it as
+     * a preset matters because the value is not memorable and an approximation
+     * such as 30 or 45 degrees produces the subtly-wrong grid alignment that
+     * isometric tile art immediately reveals.
+     */
+    readonly isometric: (options?: Omit<AuraCameraSpec, "mode">) => AuraCameraSpec;
     readonly autoFrame: (options?: {
         readonly bounds?: AuraBoundsSpec;
         readonly target?: AuraVec3;
@@ -2233,6 +2286,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";
@@ -2508,4 +2570,5 @@ interface ProductionBoundsProbe {
  * silently producing mismatched framing.
  */
 export declare function auraProductionBoundsProbes(): readonly ProductionBoundsProbe[];
+export declare function isOrthographicCameraMode(mode: AuraCameraMode): boolean;
 //# sourceMappingURL=index.d.ts.map