@aura3d/engine 3.0.0 → 4.0.0

package/dist/engine/agent-api/camera/rigs/topDown.js

@@ -0,0 +1,87 @@
+import { springDampVec3 } from "../Spring.js";
+import { distanceForFractionInContext } from "../framing.js";
+import { add, mul, subjectHeight } from "./rigUtils.js";
+const DEG = Math.PI / 180;
+export function createTopDownRig(o = {}) {
+    const pitchDeg = o.pitchDeg ?? 75;
+    const height = o.height ?? 14;
+    const deadZone = o.deadZone ?? { x: 0.1, y: 0.1 };
+    const fov = o.fov ?? 45;
+    const centreHalflife = o.centreHalflife ?? 0.12;
+    const pitch = pitchDeg * DEG;
+    // Arm: straight down for pitch 90°, else tilted back along +Z (per-frame:
+    // `back` scales with the solved altitude, not just `o.height`).
+    // Up-vector degeneracy: at ≥89.5° the view axis is (near) parallel to
+    // world-up — pass the plane forward instead (§6.4).
+    const upVec = Math.abs(pitchDeg) >= 89.5 ? [0, 0, -1] : [0, 1, 0];
+    let centre;
+    return {
+        id: "topDown",
+        continuous: true,
+        reset(pose) {
+            centre = pose ? [...pose.target] : undefined;
+        },
+        update(ctx) {
+            const refs = Array.isArray(o.target) ? o.target : [o.target].filter((t) => !!t);
+            const pts = [];
+            let maxSubjectH = 0;
+            for (const ref of refs) {
+                const s = ctx.subject(ref);
+                if (s) {
+                    pts.push(s.position);
+                    maxSubjectH = Math.max(maxSubjectH, subjectHeight(s));
+                }
+            }
+            if (pts.length === 0 && refs.length === 0)
+                pts.push(ctx.previous.target);
+            if (pts.length === 0)
+                return ctx.previous;
+            let centroid = pts[0];
+            for (let i = 1; i < pts.length; i++)
+                centroid = add(centroid, pts[i]);
+            centroid = mul(centroid, 1 / pts.length);
+            // Framing solver wins over the fixed altitude when set (#76): the
+            // tallest subject fills `subjectHeightFraction` of frame height.
+            const heightNow = o.framing !== undefined && maxSubjectH > 0
+                ? distanceForFractionInContext(maxSubjectH, fov, o.framing.subjectHeightFraction, { aspect: ctx.aspect })
+                : height;
+            // World-space dead zone on the ground plane.
+            const halfH = Math.tan(((fov / 2) * Math.PI) / 180) * heightNow;
+            const halfW = halfH * ctx.aspect;
+            if (centre === undefined)
+                centre = centroid;
+            const dzX = deadZone.x * halfW;
+            const dzZ = deadZone.y * halfH;
+            const desiredX = Math.abs(centroid[0] - centre[0]) > dzX ? centroid[0] : centre[0];
+            const desiredZ = Math.abs(centroid[2] - centre[2]) > dzZ ? centroid[2] : centre[2];
+            centre = springDampVec3(centre, [desiredX, 0, desiredZ], centreHalflife, ctx.dt);
+            // Arena clamp: the look point stays inside [edge - halfFrame, edge + halfFrame]
+            // so all four arena edges project into the frame when the arena fits.
+            if (o.bounds) {
+                const [minB, maxB] = [o.bounds.min, o.bounds.max];
+                const clampToFrame = (c, lo, hi, half) => {
+                    if ((hi - lo) / 2 > half)
+                        return (lo + hi) / 2; // arena wider than frame → centre
+                    return Math.min(Math.max(c, hi - half), lo + half);
+                };
+                centre = [
+                    clampToFrame(centre[0], minB[0], maxB[0], halfW),
+                    centre[1],
+                    clampToFrame(centre[2], minB[2], maxB[2], halfH)
+                ];
+            }
+            return {
+                position: [centre[0], heightNow, centre[2] + Math.cos(pitch) * heightNow],
+                target: centre,
+                up: upVec,
+                roll: 0,
+                fov,
+                near: Math.max(0.05, heightNow * 0.02),
+                far: ctx.previous.far
+            };
+        }
+    };
+}
+import { registerRigFactory } from "./registry.js";
+registerRigFactory("topDown", (o) => createTopDownRig(o));
+//# sourceMappingURL=topDown.js.map

package/dist/engine/agent-api/camera/rigs/topDown.js.map

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

package/dist/engine/agent-api/camera/sceneNodes.d.ts

@@ -0,0 +1,3 @@
+import type { SceneCameraNodeLike } from "./subject.js";
+export declare function flattenSceneNodes(nodes: readonly SceneCameraNodeLike[]): SceneCameraNodeLike[];
+//# sourceMappingURL=sceneNodes.d.ts.map

package/dist/engine/agent-api/camera/sceneNodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneNodes.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/camera/sceneNodes.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAgDxD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAsB9F"}

package/dist/engine/agent-api/camera/sceneNodes.js

@@ -0,0 +1,51 @@
+function scaleToVec3(scale) {
+    if (typeof scale === "number")
+        return [scale, scale, scale];
+    return scale ?? [1, 1, 1];
+}
+function hasTransform(t) {
+    return Boolean(t.position || t.rotation || t.scale || t.lookAt);
+}
+function composeTransform(parent, child) {
+    const composed = {};
+    if (parent.position || child.position) {
+        const p = parent.position ?? [0, 0, 0];
+        const c = child.position ?? [0, 0, 0];
+        composed.position = [p[0] + c[0], p[1] + c[1], p[2] + c[2]];
+    }
+    if (parent.rotation || child.rotation) {
+        const p = parent.rotation ?? [0, 0, 0];
+        const c = child.rotation ?? [0, 0, 0];
+        composed.rotation = [p[0] + c[0], p[1] + c[1], p[2] + c[2]];
+    }
+    if (parent.scale || child.scale) {
+        const p = scaleToVec3(parent.scale);
+        const c = scaleToVec3(child.scale);
+        composed.scale = [p[0] * c[0], p[1] * c[1], p[2] * c[2]];
+    }
+    composed.lookAt = child.lookAt ?? parent.lookAt;
+    return composed;
+}
+export function flattenSceneNodes(nodes) {
+    const out = [];
+    const walk = (list, parent) => {
+        for (const node of list) {
+            if (node.kind === "group" && node.children) {
+                walk(node.children, composeTransform(parent, node));
+                continue;
+            }
+            if (hasTransform(parent) &&
+                node.kind !== "effect" &&
+                node.kind !== "environment" &&
+                node.kind !== "interaction") {
+                out.push({ ...node, ...composeTransform(parent, node) });
+            }
+            else {
+                out.push(node);
+            }
+        }
+    };
+    walk(nodes, {});
+    return out;
+}
+//# sourceMappingURL=sceneNodes.js.map

package/dist/engine/agent-api/camera/sceneNodes.js.map

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

package/dist/engine/agent-api/camera/staticBounds.d.ts

@@ -0,0 +1,33 @@
+/**
+ * S8 / C-9: world-space AABBs for the static scene nodes the collision probe
+ * must see (Codex review on #911: the probe only enumerated `app.nodes`, i.e.
+ * nodes authored with `.runtime(...)`, so ordinary primitive/model walls were
+ * invisible and `collision: true` rigs passed straight through them).
+ *
+ * Conservative by design — a camera pulled in slightly early is acceptable, a
+ * camera inside a wall is not:
+ * - primitives: half-extent = size/2 × scale (box/plane/torus use the size
+ *   vector, sphere/cylinder/capsule the max component); any non-zero rotation
+ *   widens the box to the half-extent's bounding sphere;
+ * - models: only when `targetMaxDimension` bounds every axis without
+ *   loading the asset; otherwise they are skipped (asset bounds are not
+ *   known to the lane; `targetHeight`/`targetLength` fix one axis only);
+ * - `instances` expand to one box per instance, composed exactly as the
+ *   render paths do (primitive: instance transform only; model: node
+ *   transform overridden by instance fields);
+ * - nodes with a `runtime` spec are skipped here (the runtime registry
+ *   already reports their live bounds), as are invisible nodes.
+ * Results are cached per `nodes` array identity: scene specs are replaced,
+ * not mutated, so the flatten runs once per scene rather than per frame.
+ */
+import type { AuraVec3 } from "../index.js";
+import type { SceneCameraNodeLike } from "./subject.js";
+export interface StaticProbeBox {
+    readonly id: string;
+    readonly min: AuraVec3;
+    readonly max: AuraVec3;
+}
+export declare function staticSceneProbeBoxes(nodes: readonly SceneCameraNodeLike[]): StaticProbeBox[];
+/** Per-scene cache keyed on the `nodes` array identity. */
+export declare function createStaticProbeBoxSource(): (nodes: readonly SceneCameraNodeLike[] | undefined) => readonly StaticProbeBox[];
+//# sourceMappingURL=staticBounds.d.ts.map

package/dist/engine/agent-api/camera/staticBounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staticBounds.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/camera/staticBounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;CACxB;AAyDD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,cAAc,EAAE,CAqB7F;AAED,2DAA2D;AAC3D,wBAAgB,0BAA0B,IAAI,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,KAAK,SAAS,cAAc,EAAE,CAW7H"}

package/dist/engine/agent-api/camera/staticBounds.js

@@ -0,0 +1,76 @@
+import { flattenSceneNodes } from "./sceneNodes.js";
+const ROUND_SHAPES = new Set(["sphere", "cylinder", "capsule"]);
+function vec3(v, fallback) {
+    if (typeof v === "number")
+        return [v, v, v];
+    return v ?? [fallback, fallback, fallback];
+}
+function baseHalfExtent(node) {
+    if (node.kind === "primitive") {
+        const size = vec3(node.size, 1);
+        if (node.primitive && ROUND_SHAPES.has(node.primitive)) {
+            const m = Math.max(Math.abs(size[0]), Math.abs(size[1]), Math.abs(size[2])) / 2;
+            return [m, m, m];
+        }
+        return [Math.abs(size[0]) / 2, Math.abs(size[1]) / 2, Math.abs(size[2]) / 2];
+    }
+    if (node.kind === "model") {
+        // Only `targetMaxDimension` bounds every axis; `targetHeight`/`targetLength`
+        // fix one axis and keep the asset's aspect, so a d×d×d cube would
+        // under-bound wide/tall assets (Codex review on #946).
+        const d = node.targetMaxDimension;
+        if (typeof d !== "number" || !(d > 0))
+            return undefined;
+        return [d / 2, d / 2, d / 2];
+    }
+    return undefined;
+}
+function boxFor(id, half, position, rotation, scale) {
+    const s = vec3(scale, 1);
+    let h = [half[0] * Math.abs(s[0]), half[1] * Math.abs(s[1]), half[2] * Math.abs(s[2])];
+    if (rotation && (rotation[0] !== 0 || rotation[1] !== 0 || rotation[2] !== 0)) {
+        const r = Math.hypot(h[0], h[1], h[2]);
+        h = [r, r, r];
+    }
+    const p = position ?? [0, 0, 0];
+    return { id, min: [p[0] - h[0], p[1] - h[1], p[2] - h[2]], max: [p[0] + h[0], p[1] + h[1], p[2] + h[2]] };
+}
+export function staticSceneProbeBoxes(nodes) {
+    const out = [];
+    const flat = flattenSceneNodes(nodes);
+    flat.forEach((node, index) => {
+        if (node.runtime || node.visible === false)
+            return;
+        const half = baseHalfExtent(node);
+        if (!half)
+            return;
+        const id = `static:${node.name ?? node.kind}:${index}`;
+        if (node.instances && node.instances.length > 0) {
+            // Match the render paths (compiler/primitives.ts): primitive instances
+            // use only the instance transform; model instances spread the node and
+            // let instance fields override (Codex review on #946).
+            node.instances.forEach((inst, i) => {
+                const t = node.kind === "model" ? { position: node.position, rotation: node.rotation, scale: node.scale, ...inst } : inst;
+                out.push(boxFor(`${id}#${i}`, half, t.position, t.rotation, t.scale));
+            });
+            return;
+        }
+        out.push(boxFor(id, half, node.position, node.rotation, node.scale));
+    });
+    return out;
+}
+/** Per-scene cache keyed on the `nodes` array identity. */
+export function createStaticProbeBoxSource() {
+    let key;
+    let cached = [];
+    return (nodes) => {
+        if (!nodes)
+            return [];
+        if (nodes !== key) {
+            key = nodes;
+            cached = staticSceneProbeBoxes(nodes);
+        }
+        return cached;
+    };
+}
+//# sourceMappingURL=staticBounds.js.map

package/dist/engine/agent-api/camera/staticBounds.js.map

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

package/dist/engine/agent-api/camera/subject.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Subject resolution for C-22 rigs: runtime-node handle → interpolated
+ * `AuraCameraSubject`, with the legacy scene-node fallback kept distinct so
+ * `rigs.fromSpec` can reproduce the pre-controller resolution order exactly
+ * (runtime target wins; scene node only when no runtime target resolves).
+ */
+import type { AuraVec3 } from "../index.js";
+import type { AuraCameraSubject } from "../../contracts/camera.js";
+/** What a camera rig needs to know about a resolved node. */
+export interface ResolvedSubjectSource {
+    readonly position: AuraVec3;
+    readonly rotation: AuraVec3;
+}
+/** A node in the scene snapshot a follow spec may bind to (model/primitive). */
+export interface SceneCameraNodeLike {
+    readonly kind: string;
+    readonly name?: string;
+    readonly position?: AuraVec3;
+    readonly rotation?: AuraVec3;
+    readonly runtime?: {
+        readonly id?: string;
+    };
+    readonly asset?: {
+        readonly id?: string;
+    };
+}
+export interface RuntimeHandleLike {
+    readonly id: string;
+    readonly name?: string;
+    readonly tags: readonly string[];
+    readonly position: AuraVec3;
+    readonly rotation: AuraVec3;
+    readonly visible?: boolean;
+    bounds(): {
+        readonly min: AuraVec3;
+        readonly max: AuraVec3;
+    };
+}
+export interface RuntimeRegistryLike {
+    get(id: string): RuntimeHandleLike | undefined;
+    all(): readonly RuntimeHandleLike[];
+}
+/** Forward vector of a node under Euler XYZ rotation, matching `eulerToQuat`. */
+export declare function subjectForward(rotation: AuraVec3): AuraVec3;
+/**
+ * Legacy runtime-target resolution (index.ts `findRuntimeCameraTarget`):
+ * direct handle by id wins (even when hidden), then name/tag match among
+ * visible handles.
+ */
+export declare function findRuntimeTarget(registry: RuntimeRegistryLike | undefined, ref: string | undefined): ResolvedSubjectSource | undefined;
+/** Legacy scene-node fallback (model/primitive by name, asset id, or runtime id). */
+export declare function findSceneNodeTarget(nodes: readonly SceneCameraNodeLike[] | undefined, ref: string | undefined): ResolvedSubjectSource | undefined;
+/** Build the C-22 subject for a runtime handle (velocity filled by the controller). */
+export declare function subjectFromHandle(handle: RuntimeHandleLike, velocity?: AuraVec3): AuraCameraSubject;
+/** Euler-Y of a subject for target-yaw offsets — exact `rotation[1]` when the
+ * rotation quaternion is present (CCR-08-2), else yaw of `forward`. */
+export declare function subjectRotationY(subject: AuraCameraSubject): number;
+//# sourceMappingURL=subject.d.ts.map

package/dist/engine/agent-api/camera/subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/camera/subject.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,IAAI;QAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAC/C,GAAG,IAAI,SAAS,iBAAiB,EAAE,CAAC;CACrC;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EACzC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,qBAAqB,GAAG,SAAS,CAQnC;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,SAAS,EACjD,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,qBAAqB,GAAG,SAAS,CAUnC;AAED,uFAAuF;AACvF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,iBAAiB,EACzB,QAAQ,GAAE,QAAoB,GAC7B,iBAAiB,CAanB;AAED;uEACuE;AACvE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAKnE"}

package/dist/engine/agent-api/camera/subject.js

@@ -0,0 +1,57 @@
+import { quatFromEulerXYZ, quatRotateVec3, quatToEulerXYZ } from "./quat.js";
+/** Forward vector of a node under Euler XYZ rotation, matching `eulerToQuat`. */
+export function subjectForward(rotation) {
+    const q = quatFromEulerXYZ(rotation);
+    const f = quatRotateVec3(q, [0, 0, 1]);
+    const len = Math.hypot(f[0], f[1], f[2]);
+    return len > 1e-9 ? [f[0] / len, f[1] / len, f[2] / len] : [0, 0, 1];
+}
+/**
+ * Legacy runtime-target resolution (index.ts `findRuntimeCameraTarget`):
+ * direct handle by id wins (even when hidden), then name/tag match among
+ * visible handles.
+ */
+export function findRuntimeTarget(registry, ref) {
+    if (!registry || !ref)
+        return undefined;
+    const direct = registry.get(ref);
+    if (direct)
+        return { position: direct.position, rotation: direct.rotation };
+    const named = registry.all().find((h) => h.visible !== false && (h.name === ref || h.tags.includes(ref)));
+    return named ? { position: named.position, rotation: named.rotation } : undefined;
+}
+/** Legacy scene-node fallback (model/primitive by name, asset id, or runtime id). */
+export function findSceneNodeTarget(nodes, ref) {
+    if (!nodes || !ref)
+        return undefined;
+    const node = nodes.find((n) => (n.kind === "model" || n.kind === "primitive") &&
+        (n.name === ref ||
+            (n.kind === "model" && n.asset?.id === ref) ||
+            n.runtime?.id === ref));
+    return node?.position ? { position: node.position, rotation: node.rotation ?? [0, 0, 0] } : undefined;
+}
+/** Build the C-22 subject for a runtime handle (velocity filled by the controller). */
+export function subjectFromHandle(handle, velocity = [0, 0, 0]) {
+    const bounds = handle.bounds();
+    const subject = {
+        position: handle.position,
+        velocity,
+        forward: subjectForward(handle.rotation),
+        bounds: { min: bounds.min, max: bounds.max },
+        rotation: quatFromEulerXYZ(handle.rotation), // CCR-08-2
+        // V-6: model telemetry published on the handle (bicycle vehicle state
+        // {lateralG, vLong}) flows to rigs that prefer it over estimates.
+        telemetry: handle.telemetry
+    };
+    return subject;
+}
+/** Euler-Y of a subject for target-yaw offsets — exact `rotation[1]` when the
+ * rotation quaternion is present (CCR-08-2), else yaw of `forward`. */
+export function subjectRotationY(subject) {
+    const q = subject.rotation;
+    if (q)
+        return quatToEulerXYZ(q)[1];
+    const f = subject.forward;
+    return Math.atan2(f[0], f[2]);
+}
+//# sourceMappingURL=subject.js.map

package/dist/engine/agent-api/camera/subject.js.map

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

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

@@ -0,0 +1,21 @@
+/**
+ * C-06 color parsing (PRD-01) — the single parser. Grammar per PRD-01 §15
+ * Phase 1 "Color parser": `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`,
+ * `rgb()/rgba()` (comma and space syntax), `hsl()/hsla()`, the 148 CSS named
+ * colors, and numbers `0xRRGGBB` / `0xRRGGBBAA`. `parseAuraColor` returns
+ * linear-light RGBA (exact piecewise sRGB transfer via
+ * `@aura3d/rendering` ColorManagement); `parseAuraColorSrgb` returns the
+ * sRGB-encoded RGBA. Invalid input throws `AuraColorParseError` carrying the
+ * input — callers decide fallback policy (C-36 `COLOR_PARSE_FAILED` wiring is
+ * the compiler file's job after the Q-15-7 move).
+ */
+export type AuraColorInput = string | number;
+export declare class AuraColorParseError extends Error {
+    readonly input: unknown;
+    constructor(input: unknown);
+}
+/** sRGB-encoded [r,g,b,a] each 0..1. Throws AuraColorParseError on unknown input. */
+export declare function parseAuraColorSrgb(color: AuraColorInput): readonly [number, number, number, number];
+/** Linear-light RGBA — sRGB channels passed through the exact piecewise transfer. */
+export declare function parseAuraColor(color: AuraColorInput): readonly [number, number, number, number];
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/color.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;CAI3C;AAgJD,qFAAqF;AACrF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAqBnG;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAG/F"}

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

@@ -0,0 +1,201 @@
+/**
+ * C-06 color parsing (PRD-01) — the single parser. Grammar per PRD-01 §15
+ * Phase 1 "Color parser": `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`,
+ * `rgb()/rgba()` (comma and space syntax), `hsl()/hsla()`, the 148 CSS named
+ * colors, and numbers `0xRRGGBB` / `0xRRGGBBAA`. `parseAuraColor` returns
+ * linear-light RGBA (exact piecewise sRGB transfer via
+ * `@aura3d/rendering` ColorManagement); `parseAuraColorSrgb` returns the
+ * sRGB-encoded RGBA. Invalid input throws `AuraColorParseError` carrying the
+ * input — callers decide fallback policy (C-36 `COLOR_PARSE_FAILED` wiring is
+ * the compiler file's job after the Q-15-7 move).
+ */
+import { srgbToLinearChannel } from "../../rendering/index.js";
+export class AuraColorParseError extends Error {
+    input;
+    constructor(input) {
+        super(`AuraColorParseError:${String(input)}`);
+        this.input = input;
+        this.name = "AuraColorParseError";
+    }
+}
+/** The 148 CSS named colors (sRGB hex, alpha 1). */
+const NAMED_COLORS = {
+    aliceblue: 0xf0f8ff, antiquewhite: 0xfaebd7, aqua: 0x00ffff, aquamarine: 0x7fffd4,
+    azure: 0xf0ffff, beige: 0xf5f5dc, bisque: 0xffe4c4, black: 0x000000,
+    blanchedalmond: 0xffebcd, blue: 0x0000ff, blueviolet: 0x8a2be2, brown: 0xa52a2a,
+    burlywood: 0xdeb887, cadetblue: 0x5f9ea0, chartreuse: 0x7fff00, chocolate: 0xd2691e,
+    coral: 0xff7f50, cornflowerblue: 0x6495ed, cornsilk: 0xfff8dc, crimson: 0xdc143c,
+    cyan: 0x00ffff, darkblue: 0x00008b, darkcyan: 0x008b8b, darkgoldenrod: 0xb8860b,
+    darkgray: 0xa9a9a9, darkgreen: 0x006400, darkgrey: 0xa9a9a9, darkkhaki: 0xbdb76b,
+    darkmagenta: 0x8b008b, darkolivegreen: 0x556b2f, darkorange: 0xff8c00, darkorchid: 0x9932cc,
+    darkred: 0x8b0000, darksalmon: 0xe9967a, darkseagreen: 0x8fbc8f, darkslateblue: 0x483d8b,
+    darkslategray: 0x2f4f4f, darkslategrey: 0x2f4f4f, darkturquoise: 0x00ced1, darkviolet: 0x9400d3,
+    deeppink: 0xff1493, deepskyblue: 0x00bfff, dimgray: 0x696969, dimgrey: 0x696969,
+    dodgerblue: 0x1e90ff, firebrick: 0xb22222, floralwhite: 0xfffaf0, forestgreen: 0x228b22,
+    fuchsia: 0xff00ff, gainsboro: 0xdcdcdc, ghostwhite: 0xf8f8ff, gold: 0xffd700,
+    goldenrod: 0xdaa520, gray: 0x808080, green: 0x008000, greenyellow: 0xadff2f,
+    grey: 0x808080, honeydew: 0xf0fff0, hotpink: 0xff69b4, indianred: 0xcd5c5c,
+    indigo: 0x4b0082, ivory: 0xfffff0, khaki: 0xf0e68c, lavender: 0xe6e6fa,
+    lavenderblush: 0xfff0f5, lawngreen: 0x7cfc00, lemonchiffon: 0xfffacd, lightblue: 0xadd8e6,
+    lightcoral: 0xf08080, lightcyan: 0xe0ffff, lightgoldenrodyellow: 0xfafad2, lightgray: 0xd3d3d3,
+    lightgreen: 0x90ee90, lightgrey: 0xd3d3d3, lightpink: 0xffb6c1, lightsalmon: 0xffa07a,
+    lightseagreen: 0x20b2aa, lightskyblue: 0x87cefa, lightslategray: 0x778899, lightslategrey: 0x778899,
+    lightsteelblue: 0xb0c4de, lightyellow: 0xffffe0, lime: 0x00ff00, limegreen: 0x32cd32,
+    linen: 0xfaf0e6, magenta: 0xff00ff, maroon: 0x800000, mediumaquamarine: 0x66cdaa,
+    mediumblue: 0x0000cd, mediumorchid: 0xba55d3, mediumpurple: 0x9370db, mediumseagreen: 0x3cb371,
+    mediumslateblue: 0x7b68ee, mediumspringgreen: 0x00fa9a, mediumturquoise: 0x48d1cc, mediumvioletred: 0xc71585,
+    midnightblue: 0x191970, mintcream: 0xf5fffa, mistyrose: 0xffe4e1, moccasin: 0xffe4b5,
+    navajowhite: 0xffdead, navy: 0x000080, oldlace: 0xfdf5e6, olive: 0x808000,
+    olivedrab: 0x6b8e23, orange: 0xffa500, orangered: 0xff4500, orchid: 0xda70d6,
+    palegoldenrod: 0xeee8aa, palegreen: 0x98fb98, paleturquoise: 0xafeeee, palevioletred: 0xdb7093,
+    papayawhip: 0xffefd5, peachpuff: 0xffdab9, peru: 0xcd853f, pink: 0xffc0cb,
+    plum: 0xdda0dd, powderblue: 0xb0e0e6, purple: 0x800080, rebeccapurple: 0x663399,
+    red: 0xff0000, rosybrown: 0xbc8f8f, royalblue: 0x4169e1, saddlebrown: 0x8b4513,
+    salmon: 0xfa8072, sandybrown: 0xf4a460, seagreen: 0x2e8b57, seashell: 0xfff5ee,
+    sienna: 0xa0522d, silver: 0xc0c0c0, skyblue: 0x87ceeb, slateblue: 0x6a5acd,
+    slategray: 0x708090, slategrey: 0x708090, snow: 0xfffafa, springgreen: 0x00ff7f,
+    steelblue: 0x4682b4, tan: 0xd2b48c, teal: 0x008080, thistle: 0xd8bfd8,
+    tomato: 0xff6347, turquoise: 0x40e0d0, violet: 0xee82ee, wheat: 0xf5deb3,
+    white: 0xffffff, whitesmoke: 0xf5f5f5, yellow: 0xffff00, yellowgreen: 0x9acd32
+};
+function parseChannel(token) {
+    const t = token.trim();
+    if (t.endsWith("%")) {
+        const pct = Number(t.slice(0, -1));
+        if (!Number.isFinite(pct))
+            throw new AuraColorParseError(token);
+        return Math.max(0, Math.min(1, pct / 100));
+    }
+    const value = Number(t);
+    if (!Number.isFinite(value))
+        throw new AuraColorParseError(token);
+    return Math.max(0, Math.min(1, value / 255));
+}
+function parseAlpha(token) {
+    if (token === undefined)
+        return 1;
+    const t = token.trim();
+    if (t.endsWith("%")) {
+        const pct = Number(t.slice(0, -1));
+        if (!Number.isFinite(pct))
+            throw new AuraColorParseError(token);
+        return Math.max(0, Math.min(1, pct / 100));
+    }
+    const value = Number(t);
+    if (!Number.isFinite(value))
+        throw new AuraColorParseError(token);
+    return Math.max(0, Math.min(1, value));
+}
+function splitFunctionArgs(body) {
+    // Comma syntax: rgb(r, g, b[, a]); space syntax: rgb(r g b / a).
+    if (body.includes(",")) {
+        return body.split(",").map((part) => part.trim());
+    }
+    const slash = body.split("/").map((part) => part.trim());
+    const first = slash[0].split(/\s+/).filter((part) => part.length > 0);
+    if (slash.length > 1)
+        first.push(slash[1]);
+    return first;
+}
+function parseFunctionColor(name, body) {
+    const args = splitFunctionArgs(body);
+    if (name === "rgb" || name === "rgba") {
+        if (args.length !== 3 && args.length !== 4)
+            throw new AuraColorParseError(`${name}(${body})`);
+        return [parseChannel(args[0]), parseChannel(args[1]), parseChannel(args[2]), parseAlpha(args[3])];
+    }
+    if (name === "hsl" || name === "hsla") {
+        if (args.length !== 3 && args.length !== 4)
+            throw new AuraColorParseError(`${name}(${body})`);
+        const hRaw = args[0].trim();
+        const hDeg = hRaw.endsWith("deg") ? Number(hRaw.slice(0, -3)) : hRaw.endsWith("turn") ? Number(hRaw.slice(0, -4)) * 360 : Number(hRaw);
+        const s = args[1].trim().endsWith("%") ? Number(args[1].trim().slice(0, -1)) / 100 : Number(args[1]);
+        const l = args[2].trim().endsWith("%") ? Number(args[2].trim().slice(0, -1)) / 100 : Number(args[2]);
+        if (!Number.isFinite(hDeg) || !Number.isFinite(s) || !Number.isFinite(l))
+            throw new AuraColorParseError(`${name}(${body})`);
+        const a = parseAlpha(args[3]);
+        return hslToRgb(hDeg, Math.max(0, Math.min(1, s)), Math.max(0, Math.min(1, l)), a);
+    }
+    throw new AuraColorParseError(`${name}(${body})`);
+}
+function hslToRgb(hDeg, s, l, a) {
+    const h = ((hDeg % 360) + 360) % 360 / 360;
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const hue = (t) => {
+        let u = t;
+        if (u < 0)
+            u += 1;
+        if (u > 1)
+            u -= 1;
+        if (u < 1 / 6)
+            return p + (q - p) * 6 * u;
+        if (u < 1 / 2)
+            return q;
+        if (u < 2 / 3)
+            return p + (q - p) * (2 / 3 - u) * 6;
+        return p;
+    };
+    return [hue(h + 1 / 3), hue(h), hue(h - 1 / 3), a];
+}
+function parseHex(body) {
+    switch (body.length) {
+        case 3:
+            return [
+                parseInt(body[0] + body[0], 16) / 255,
+                parseInt(body[1] + body[1], 16) / 255,
+                parseInt(body[2] + body[2], 16) / 255,
+                1
+            ];
+        case 4:
+            return [
+                parseInt(body[0] + body[0], 16) / 255,
+                parseInt(body[1] + body[1], 16) / 255,
+                parseInt(body[2] + body[2], 16) / 255,
+                parseInt(body[3] + body[3], 16) / 255
+            ];
+        case 6: {
+            const v = Number.parseInt(body, 16);
+            return [((v >> 16) & 0xff) / 255, ((v >> 8) & 0xff) / 255, (v & 0xff) / 255, 1];
+        }
+        case 8: {
+            const v = Number.parseInt(body, 16);
+            const rgb = v >>> 8;
+            return [((rgb >> 16) & 0xff) / 255, ((rgb >> 8) & 0xff) / 255, (rgb & 0xff) / 255, (v & 0xff) / 255];
+        }
+        default:
+            throw new AuraColorParseError(`#${body}`);
+    }
+}
+/** sRGB-encoded [r,g,b,a] each 0..1. Throws AuraColorParseError on unknown input. */
+export function parseAuraColorSrgb(color) {
+    if (typeof color === "number" && Number.isFinite(color)) {
+        const v = color >>> 0;
+        // 0xRRGGBBAA when the top byte is non-zero-opaque meaningful; heuristic:
+        // treat > 0xFFFFFF as RGBA, else RGB (matches the PR 0a stub semantics).
+        if (color > 0xffffff) {
+            return [((v >> 24) & 0xff) / 255, ((v >> 16) & 0xff) / 255, ((v >> 8) & 0xff) / 255, (v & 0xff) / 255];
+        }
+        return [((v >> 16) & 0xff) / 255, ((v >> 8) & 0xff) / 255, (v & 0xff) / 255, 1];
+    }
+    if (typeof color !== "string")
+        throw new AuraColorParseError(color);
+    const input = color.trim();
+    const hexMatch = /^#([0-9a-f]+)$/i.exec(input);
+    if (hexMatch)
+        return parseHex(hexMatch[1]);
+    const fnMatch = /^(rgb|rgba|hsl|hsla)\((.+)\)$/i.exec(input);
+    if (fnMatch)
+        return parseFunctionColor(fnMatch[1].toLowerCase(), fnMatch[2]);
+    const named = NAMED_COLORS[input.toLowerCase()];
+    if (named !== undefined) {
+        return [((named >> 16) & 0xff) / 255, ((named >> 8) & 0xff) / 255, (named & 0xff) / 255, 1];
+    }
+    throw new AuraColorParseError(color);
+}
+/** Linear-light RGBA — sRGB channels passed through the exact piecewise transfer. */
+export function parseAuraColor(color) {
+    const [r, g, b, a] = parseAuraColorSrgb(color);
+    return [srgbToLinearChannel(r), srgbToLinearChannel(g), srgbToLinearChannel(b), a];
+}
+//# sourceMappingURL=color.js.map