@aura3d/engine 2.0.3 → 3.0.0

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

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

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

@@ -0,0 +1,41 @@
+import { AnimationAction, AnimationClip, AnimationLayer, AnimationMixer, AnimationTrack, type AnimationClipDescriptor, type AnimationEvent, type AnimationEventMarker, type AnimationLayerOptions, type AnimationMixerOptions, type AnimationMixerSnapshot, type AnimationTarget, type AnimationTrackDescriptor, type AnimationValue, type LoopMode } from "../../animation/index.js";
+export { AnimationAction, AnimationClip, AnimationLayer, AnimationMixer, AnimationTrack };
+export type { AnimationClipDescriptor, AnimationEvent, AnimationEventMarker, AnimationLayerOptions, AnimationMixerOptions, AnimationMixerSnapshot, AnimationTrackDescriptor, AnimationValue, LoopMode };
+export interface RootAnimationMixerOptions extends AnimationMixerOptions {
+    readonly target?: AnimationTarget;
+    readonly timeScale?: number;
+}
+export interface RootAnimationActionOptions {
+    readonly weight?: number;
+    readonly timeScale?: number;
+    readonly loop?: LoopMode;
+    readonly autoplay?: boolean;
+}
+export interface RootAnimationEventMarkerOptions {
+    readonly name: string;
+    readonly time: number;
+    readonly payload?: unknown;
+}
+export interface RootAnimationCrossFadeOptions {
+    readonly inertial?: boolean;
+    readonly halfLife?: number;
+}
+/**
+ * Root safe API entry for the three.js `AnimationMixer` workflow: mixer,
+ * action, track, event, timeScale, crossfade, and layers are all reachable
+ * from `@aura3d/engine` through these builders. Every builder fails loud:
+ * invalid input throws naming the builder, and ignored operations on the
+ * underlying mixer/action/layer warn or throw naming that API.
+ */
+export declare function createAnimationMixer(options?: RootAnimationMixerOptions): AnimationMixer;
+export declare function createAnimationTrack<T extends AnimationValue = AnimationValue>(descriptor: AnimationTrackDescriptor<T>): AnimationTrack<T>;
+export declare function createAnimationClip(descriptor: AnimationClipDescriptor): AnimationClip;
+export declare function createAnimationAction(clip: AnimationClip, options?: RootAnimationActionOptions): AnimationAction;
+export declare function createAnimationLayer(name: string, options?: number | AnimationLayerOptions): AnimationLayer;
+export declare function createAnimationEventMarker(options: RootAnimationEventMarkerOptions): AnimationEventMarker;
+export declare function subscribeAnimationEvents(mixer: AnimationMixer, listener: (event: AnimationEvent) => void): () => void;
+export declare function setAnimationTimeScale(target: AnimationMixer | AnimationAction, timeScale: number): void;
+export declare function crossFadeAnimations(mixer: AnimationMixer, from: AnimationAction, to: AnimationAction, duration: number, options?: RootAnimationCrossFadeOptions): void;
+export declare function attachAnimationLayer(mixer: AnimationMixer, layer: AnimationLayer): AnimationLayer;
+export declare function assignActionToAnimationLayer(layer: AnimationLayer, action: AnimationAction): AnimationLayer;
+//# sourceMappingURL=AnimationMixerBuilders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AnimationMixerBuilders.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/AnimationMixerBuilders.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,EACd,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,cAAc,EACf,CAAC;AACF,YAAY,EACV,uBAAuB,EACvB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,QAAQ,EACT,CAAC;AAEF,MAAM,WAAW,yBAA0B,SAAQ,qBAAqB;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAaD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,yBAA8B,GAAG,cAAc,CAY5F;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAC5E,UAAU,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACtC,cAAc,CAAC,CAAC,CAAC,CAQnB;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,uBAAuB,GAAG,aAAa,CAKtF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,GAAE,0BAA+B,GAAG,eAAe,CA2BpH;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,qBAAyB,GAAG,cAAc,CAK9G;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,+BAA+B,GAAG,oBAAoB,CAazG;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GACxC,MAAM,IAAI,CAQZ;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAQvG;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,eAAe,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,6BAAkC,GAC1C,IAAI,CAYN;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CASjG;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,eAAe,GAAG,cAAc,CAS3G"}

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

@@ -0,0 +1,146 @@
+import { AnimationAction, AnimationClip, AnimationLayer, AnimationMixer, AnimationTrack } from "../../animation/index.js";
+export { AnimationAction, AnimationClip, AnimationLayer, AnimationMixer, AnimationTrack };
+const ANIMATION_TRACK_VALUE_TYPES = new Set([
+    "scalar",
+    "vector3",
+    "quaternion",
+    "number-array",
+    "boolean",
+    "string"
+]);
+const ANIMATION_ACTION_LOOPS = ["once", "repeat", "pingpong"];
+/**
+ * Root safe API entry for the three.js `AnimationMixer` workflow: mixer,
+ * action, track, event, timeScale, crossfade, and layers are all reachable
+ * from `@aura3d/engine` through these builders. Every builder fails loud:
+ * invalid input throws naming the builder, and ignored operations on the
+ * underlying mixer/action/layer warn or throw naming that API.
+ */
+export function createAnimationMixer(options = {}) {
+    if (options.timeScale !== undefined && (!Number.isFinite(options.timeScale) || options.timeScale < 0)) {
+        throw new Error("createAnimationMixer: timeScale must be finite and non-negative.");
+    }
+    if (options.rootMotionScale !== undefined && !Number.isFinite(options.rootMotionScale)) {
+        throw new Error("createAnimationMixer: rootMotionScale must be finite.");
+    }
+    const mixer = new AnimationMixer(options.target, options);
+    if (options.timeScale !== undefined) {
+        mixer.setTimeScale(options.timeScale);
+    }
+    return mixer;
+}
+export function createAnimationTrack(descriptor) {
+    if (!descriptor || typeof descriptor !== "object") {
+        throw new Error("createAnimationTrack: descriptor is required.");
+    }
+    if (!ANIMATION_TRACK_VALUE_TYPES.has(descriptor.valueType)) {
+        throw new Error(`createAnimationTrack: unknown valueType "${String(descriptor.valueType)}" for target "${String(descriptor.target)}".`);
+    }
+    return new AnimationTrack(descriptor);
+}
+export function createAnimationClip(descriptor) {
+    if (!descriptor || typeof descriptor !== "object") {
+        throw new Error("createAnimationClip: descriptor is required.");
+    }
+    return new AnimationClip(descriptor);
+}
+export function createAnimationAction(clip, options = {}) {
+    if (!(clip instanceof AnimationClip)) {
+        throw new Error("createAnimationAction: clip must be an AnimationClip created by createAnimationClip.");
+    }
+    if (options.weight !== undefined && (!Number.isFinite(options.weight) || options.weight < 0)) {
+        throw new Error("createAnimationAction: weight must be finite and non-negative.");
+    }
+    if (options.timeScale !== undefined && (!Number.isFinite(options.timeScale) || options.timeScale < 0)) {
+        throw new Error("createAnimationAction: timeScale must be finite and non-negative.");
+    }
+    if (options.loop !== undefined && !ANIMATION_ACTION_LOOPS.includes(options.loop)) {
+        throw new Error(`createAnimationAction: loop must be one of ${ANIMATION_ACTION_LOOPS.join("|")}.`);
+    }
+    const action = new AnimationAction(clip);
+    if (options.weight !== undefined) {
+        action.setWeight(options.weight);
+    }
+    if (options.timeScale !== undefined) {
+        action.setTimeScale(options.timeScale);
+    }
+    if (options.loop !== undefined) {
+        action.setLoop(options.loop);
+    }
+    if (options.autoplay ?? true) {
+        action.play();
+    }
+    return action;
+}
+export function createAnimationLayer(name, options = 1) {
+    if (typeof name !== "string" || name.trim().length === 0) {
+        throw new Error("createAnimationLayer: name must be a non-empty string.");
+    }
+    return new AnimationLayer(name, options);
+}
+export function createAnimationEventMarker(options) {
+    if (!options || typeof options !== "object") {
+        throw new Error("createAnimationEventMarker: options are required.");
+    }
+    if (typeof options.name !== "string" || options.name.trim().length === 0) {
+        throw new Error("createAnimationEventMarker: name must be a non-empty string.");
+    }
+    if (!Number.isFinite(options.time) || options.time < 0) {
+        throw new Error("createAnimationEventMarker: time must be finite and non-negative.");
+    }
+    return options.payload === undefined
+        ? { name: options.name, time: options.time }
+        : { name: options.name, time: options.time, payload: options.payload };
+}
+export function subscribeAnimationEvents(mixer, listener) {
+    if (!(mixer instanceof AnimationMixer)) {
+        throw new Error("subscribeAnimationEvents: mixer must be an AnimationMixer created by createAnimationMixer.");
+    }
+    if (typeof listener !== "function") {
+        throw new Error("subscribeAnimationEvents: listener must be a function.");
+    }
+    return mixer.onEvent(listener);
+}
+export function setAnimationTimeScale(target, timeScale) {
+    if (!(target instanceof AnimationMixer) && !(target instanceof AnimationAction)) {
+        throw new Error("setAnimationTimeScale: target must be an AnimationMixer or an AnimationAction.");
+    }
+    if (!Number.isFinite(timeScale) || timeScale < 0) {
+        throw new Error("setAnimationTimeScale: timeScale must be finite and non-negative.");
+    }
+    target.setTimeScale(timeScale);
+}
+export function crossFadeAnimations(mixer, from, to, duration, options = {}) {
+    if (!(mixer instanceof AnimationMixer)) {
+        throw new Error("crossFadeAnimations: mixer must be an AnimationMixer created by createAnimationMixer.");
+    }
+    if (options.inertial) {
+        mixer.inertialCrossFade(from, to, options.halfLife);
+        return;
+    }
+    if (options.halfLife !== undefined) {
+        throw new Error("crossFadeAnimations: halfLife requires the inertial option.");
+    }
+    mixer.crossFade(from, to, duration);
+}
+export function attachAnimationLayer(mixer, layer) {
+    if (!(mixer instanceof AnimationMixer)) {
+        throw new Error("attachAnimationLayer: mixer must be an AnimationMixer created by createAnimationMixer.");
+    }
+    if (!(layer instanceof AnimationLayer)) {
+        throw new Error("attachAnimationLayer: layer must be an AnimationLayer created by createAnimationLayer.");
+    }
+    mixer.addLayer(layer);
+    return layer;
+}
+export function assignActionToAnimationLayer(layer, action) {
+    if (!(layer instanceof AnimationLayer)) {
+        throw new Error("assignActionToAnimationLayer: layer must be an AnimationLayer created by createAnimationLayer.");
+    }
+    if (!(action instanceof AnimationAction)) {
+        throw new Error("assignActionToAnimationLayer: action must be an AnimationAction created by createAnimationAction.");
+    }
+    layer.add(action);
+    return layer;
+}
+//# sourceMappingURL=AnimationMixerBuilders.js.map

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

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

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

@@ -0,0 +1,17 @@
+import { type CompressedTextureDecoderProbes, type CompressedTextureSupportDiagnostics, type CompressedTextureSupportRequest, type KTX2BasisTargetFormat } from "../../assets/browser-index.js";
+/**
+ * Root one-call decoder setup (muse3jsparity-PRD M2).
+ *
+ * Thin async wrapper over the package-level `ensureCompressedTextureSupport`:
+ * draco/meshopt default off, ktx2 defaults on, and every probe defaults to
+ * fail-closed (unavailable) unless the route injects real capability probes.
+ * Diagnostics report per-decoder status plus the GPU-aware KTX2 target, so a
+ * route can assert support before streaming compressed textures instead of
+ * discovering a missing decoder mid-load.
+ */
+export declare function ensureAssetDecoders(request?: CompressedTextureSupportRequest, probes?: CompressedTextureDecoderProbes): Promise<CompressedTextureSupportDiagnostics>;
+export declare const assets: {
+    readonly ensureDecoders: typeof ensureAssetDecoders;
+};
+export type { CompressedTextureDecoderProbes, CompressedTextureSupportDiagnostics, CompressedTextureSupportRequest, KTX2BasisTargetFormat };
+//# sourceMappingURL=AssetDecoders.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AssetDecoders.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/AssetDecoders.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,8BAA8B,EACnC,KAAK,mCAAmC,EACxC,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,+BAAoC,EAC7C,MAAM,GAAE,8BAAmC,GAC1C,OAAO,CAAC,mCAAmC,CAAC,CAE9C;AAED,eAAO,MAAM,MAAM;;CAET,CAAC;AAEX,YAAY,EACV,8BAA8B,EAC9B,mCAAmC,EACnC,+BAA+B,EAC/B,qBAAqB,EACtB,CAAC"}

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

@@ -0,0 +1,18 @@
+import { ensureCompressedTextureSupport } from "../../assets/browser-index.js";
+/**
+ * Root one-call decoder setup (muse3jsparity-PRD M2).
+ *
+ * Thin async wrapper over the package-level `ensureCompressedTextureSupport`:
+ * draco/meshopt default off, ktx2 defaults on, and every probe defaults to
+ * fail-closed (unavailable) unless the route injects real capability probes.
+ * Diagnostics report per-decoder status plus the GPU-aware KTX2 target, so a
+ * route can assert support before streaming compressed textures instead of
+ * discovering a missing decoder mid-load.
+ */
+export async function ensureAssetDecoders(request = {}, probes = {}) {
+    return ensureCompressedTextureSupport(request, probes);
+}
+export const assets = {
+    ensureDecoders: ensureAssetDecoders
+};
+//# sourceMappingURL=AssetDecoders.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AssetDecoders.js","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/AssetDecoders.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAK/B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAA2C,EAAE,EAC7C,SAAyC,EAAE;IAE3C,OAAO,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,cAAc,EAAE,mBAAmB;CAC3B,CAAC"}

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

@@ -0,0 +1,174 @@
+/**
+ * Root gameplay-decals builder (PART C4).
+ *
+ * The projection geometry is package-level and real
+ * (`createProjectedDecalGeometry` / `createRaycastProjectedDecalGeometry` in
+ * `@aura3d/rendering`): clipped, normal-offset, UV-mapped triangles. This
+ * module is the missing public root surface: `decals.project({ texture, size,
+ * fade })` shapes those projections into ordinary root scene nodes so a
+ * `createAuraApp` route can author bullet holes, scorch marks, and spray tags
+ * without deep-importing the renderer.
+ *
+ * How a root decal survives the frame:
+ * - Geometry carries a normal offset (default 0.012 world units) baked into
+ *   the projected vertices, so the decal surface sits provably off its target.
+ * - The material is transparent (opacity < 1), which the root production
+ *   bridge already maps to blend-on, depthWrite-off, cull-none render state.
+ * - The descriptor records the intended polygon offset ({ factor: -2,
+ *   units: -2 }) alongside the fade envelope. Root has no native
+ *   polygon-offset/depth-fade sampler yet, so grazing-angle z-fighting is
+ *   defeated the portable way: the angle fade drives opacity to zero before
+ *   the view goes edge-on (see `resolveDecalFadeOpacity`), exactly where
+ *   coplanar flicker would appear.
+ *
+ * Deferred-decal budget note: root renders decals forward as transparent
+ * geometry — one draw call per decal. There is no deferred decal pass at
+ * root; `AURA_DECAL_MAX_DECALS` (32) is the authoring budget and
+ * `decals.telemetry()` reports the live count against it. Exceeding the
+ * budget never drops decals silently: telemetry flags `overBudget` and the
+ * route decides (fade far decals, recycle, or accept the cost).
+ */
+import { type ProjectedDecalBox, type ProjectedDecalTriangleMesh } from "../../rendering/index.js";
+import { AuraNodeBuilder } from "./index.js";
+import type { AuraAssetRef, AuraColor, AuraPrimitiveNode, AuraSceneNode, AuraVec3 } from "./index.js";
+/** Root authoring budget: forward-rendered transparent decals, one draw each. */
+export declare const AURA_DECAL_MAX_DECALS = 32;
+/**
+ * Deferred-decal budget note, kept next to the constant so routes quote the
+ * same sentence as telemetry. Root has no deferred decal pass; decals are
+ * forward transparent geometry until one lands.
+ */
+export declare const AURA_DECAL_BUDGET_NOTE: string;
+export interface AuraDecalFadeOptions {
+    /** Incidence degrees where the angle fade begins (head-on = 0). Default 55. */
+    readonly angleStart?: number;
+    /** Incidence degrees where the decal is fully faded (grazing = 90). Default 80. */
+    readonly angleEnd?: number;
+    /** Distance where the depth fade begins. Default 0 (no near fade). */
+    readonly near?: number;
+    /** Distance where the decal is fully faded. Default Infinity (no depth fade). */
+    readonly far?: number;
+}
+export interface AuraDecalPolygonOffset {
+    readonly factor: number;
+    readonly units: number;
+}
+export interface AuraDecalProjectOptions {
+    /** Typed texture asset for the decal albedo. Optional: falls back to `color`. */
+    readonly texture?: AuraAssetRef<"texture">;
+    /** Flat decal color (linearized by the bridge). Default "#f5f5f5". */
+    readonly color?: AuraColor;
+    /** World-space width, or [width, height]. Must be positive. */
+    readonly size: number | readonly [number, number];
+    /** Angle + depth fade envelope. Defaults fade 55°→80°, no depth fade. */
+    readonly fade?: AuraDecalFadeOptions;
+    /** Base opacity before fading. Default 0.85. Must be in (0, 1). */
+    readonly opacity?: number;
+    /** World position of the decal center. Default [0, 0, 0]. */
+    readonly position?: AuraVec3;
+    /** Euler rotation radians applied to the quad. Default [0, 0, 0]. */
+    readonly rotation?: AuraVec3;
+    /** Surface normal the decal faces; used for fade evaluation. Default [0, 0, 1]. */
+    readonly normal?: AuraVec3;
+    /** Intended polygon offset, recorded on the descriptor. Default { factor: -2, units: -2 }. */
+    readonly polygonOffset?: AuraDecalPolygonOffset;
+    /** World units the decal floats off its surface. Default 0.012. */
+    readonly normalOffset?: number;
+    readonly roughness?: number;
+    readonly metallic?: number;
+    readonly name?: string;
+}
+export interface AuraDecalDescriptor {
+    readonly size: readonly [number, number];
+    readonly baseOpacity: number;
+    readonly fade: Required<Pick<AuraDecalFadeOptions, "angleStart" | "angleEnd" | "near">> & {
+        readonly far: number;
+    };
+    readonly polygonOffset: AuraDecalPolygonOffset;
+    readonly normalOffset: number;
+    readonly normal: AuraVec3;
+    readonly textureUrl?: string;
+}
+/** A root decal node: an ordinary primitive plus its recorded decal descriptor. */
+export interface AuraDecalNode extends AuraPrimitiveNode {
+    readonly decal: AuraDecalDescriptor;
+}
+export interface AuraDecalProjectOntoMeshOptions extends Omit<AuraDecalProjectOptions, "position" | "rotation" | "normal" | "size"> {
+    /** Source mesh to clip the projection against (positions + normals + indices). */
+    readonly mesh: ProjectedDecalTriangleMesh;
+    /** Ray from above the surface toward it; the hit orients the projector. */
+    readonly ray: {
+        readonly origin: AuraVec3;
+        readonly direction: AuraVec3;
+    };
+    /** World-space projector footprint [width, height, depth]. Depth default 0.18. */
+    readonly size: number | readonly [number, number] | readonly [number, number, number];
+    readonly maxDistance?: number;
+    readonly includeBackfaces?: boolean;
+    readonly upHint?: AuraVec3;
+    readonly shape?: "box" | "ellipse";
+    readonly ellipseSegments?: number;
+}
+export interface AuraDecalFadeSample {
+    readonly normal: AuraVec3;
+    readonly cameraPosition: AuraVec3;
+    readonly decalPosition: AuraVec3;
+    readonly distance?: number;
+    readonly fade?: AuraDecalFadeOptions;
+    readonly baseOpacity?: number;
+}
+export interface AuraDecalBudgetTelemetry {
+    readonly kind: "aura-decal-budget";
+    readonly decalCount: number;
+    readonly maxDecals: number;
+    readonly overBudget: boolean;
+    readonly estimatedDrawCalls: number;
+    readonly note: string;
+    readonly allPolygonOffset: boolean;
+    readonly angleFadeDecals: number;
+    readonly depthFadeDecals: number;
+    /** Largest live decal count observed via `decals.telemetry()` this session. */
+    readonly maxObservedDecals: number;
+}
+/**
+ * Author a free-floating root decal quad. Transparent, depth-write-off by
+ * bridge convention (opacity < 1), normal-offset intent recorded on the
+ * descriptor for the projected path.
+ */
+export declare function projectDecal(options: AuraDecalProjectOptions): AuraNodeBuilder<AuraDecalNode>;
+/**
+ * Project a decal onto a source mesh through the real package-level
+ * projector and return it as a root `custom` primitive node. The clipped
+ * geometry (with baked normal offset + UVs) becomes the node's custom
+ * geometry spec; the descriptor matches `projectDecal`.
+ */
+export declare function projectDecalOntoMesh(options: AuraDecalProjectOntoMeshOptions): AuraNodeBuilder<AuraDecalNode>;
+/** Box-projected variant for callers that already solved placement (no raycast). */
+export declare function projectDecalIntoBox(mesh: ProjectedDecalTriangleMesh, box: ProjectedDecalBox, options?: Omit<AuraDecalProjectOptions, "position" | "rotation" | "normal" | "size"> & {
+    readonly size?: number | readonly [number, number];
+}): AuraNodeBuilder<AuraDecalNode>;
+/**
+ * Evaluate the decal fade envelope for one camera sample. Head-on and near
+ * is `baseOpacity`; past `angleEnd` incidence or `far` distance is 0. Pure
+ * and unit-tested; the browser proof probes this against live pixels.
+ */
+export declare function resolveDecalFadeOpacity(sample: AuraDecalFadeSample): number;
+/**
+ * Max-decal telemetry over a flattened scene (or any node list). Counts
+ * decal nodes, compares against `AURA_DECAL_MAX_DECALS`, and records the
+ * session max. Never throws on foreign nodes.
+ */
+export declare function collectDecalBudgetTelemetry(nodes: readonly AuraSceneNode[], maxDecals?: number): AuraDecalBudgetTelemetry;
+/** Reset the session max-observed counter (tests only). */
+export declare function resetDecalTelemetry(): void;
+export declare const decals: {
+    readonly project: typeof projectDecal;
+    readonly projectOntoMesh: typeof projectDecalOntoMesh;
+    readonly projectIntoBox: typeof projectDecalIntoBox;
+    readonly resolveFadeOpacity: typeof resolveDecalFadeOpacity;
+    readonly telemetry: typeof collectDecalBudgetTelemetry;
+    readonly resetTelemetry: typeof resetDecalTelemetry;
+    readonly maxDecals: 32;
+    readonly budgetNote: string;
+};
+//# sourceMappingURL=Decals.d.ts.map

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

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