@aura3d/engine 3.0.0 → 4.0.0

package/dist/engine/agent-api/nodes/effects.d.ts

@@ -0,0 +1,111 @@
+import type { AuraEffectNode } from "../nodes/types.js";
+import { AuraNodeBuilder } from "../nodes/builder.js";
+import type { AuraBlendMode } from "../../../rendering/contracts/index.js";
+import type { AuraLegacyParticleFields, AuraParticleEmitterOptions } from "../../contracts/effects.js";
+/**
+ * Lane node-option surface: `AuraEffectNode` (shared `agent-api/index.ts`,
+ * prd15) does not yet declare the PRD-07 §6.2.9–11 fields, so the builders
+ * take a widened option bag and copy defined fields through
+ * `withEmitterOptions` — identical to the §6.2 emitter-option pattern above.
+ */
+type VfxNodeOptions = Omit<AuraEffectNode, "kind" | "effect"> & Record<string, unknown>;
+export declare const vfxEffectBuilders: {
+    /**
+     * §6.6/F-07-01 — the builder records ONLY authored fields; C-21 defaults are
+     * applied at resolve time by compiler/fog.ts under A3D_QR_VFX_FOG (a bare
+     * `effects.fog()` → height defaults; a legacy `density`-only call → exp2 +
+     * maxOpacity 1). Flag-off compile reads `?? 0.12`/`?? "#9fb7d9"` so the
+     * uniforms are unchanged.
+     */
+    fog: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+    cinematicBloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * A5 volumetric fog (muse3jsparity-PRD): builds a DISTINCT "volumetric-fog"
+     * node (never plain fog) that submits the depth-aware inscatter pass plus
+     * forward GPU height-fog terms. quality "off" keeps forward exp2 fog only.
+     */
+    volumetricFog: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    depthFog: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root outline node (muse3jsparity-PRD A3): native outline pass, width in
+     * pixels clamped to the device range 1-6 by the bridge.
+     */
+    outline: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root screen-space reflections node (muse3jsparity-PRD A3): submits the
+     * native SSR pass against renderer-owned depth where available.
+     */
+    screenSpaceReflections: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root depth-of-field node (muse3jsparity-PRD A3). focus is a
+     * linear-distance fraction (0 = near plane, 1 = far plane); aperture widens
+     * the focus transition band (game-tuned control, not a physical f-stop).
+     */
+    depthOfField: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root motion-blur node: renderer-owned GPU velocity for opaque rigid geometry.
+     * Unsupported deforming/transparent/instanced geometry emits a named warning.
+     */
+    motionBlur: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    rain: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    snow: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Flipbook explosion/muzzle-flash sprite sheet (muse3jsparity-PRD D4).
+     * Under A3D_QR_VFX it draws through the particle pass: one upright sprite
+     * of world `size`, frame = age · `frameRate` over `spriteColumns ×
+     * spriteRows` (wrapping unless `loop: false`), sampling the built-in
+     * seeded `fireball` sheet. `prewarm` starts the sprite that many seconds in.
+     */
+    flipbook: (options?: Omit<AuraEffectNode, "kind" | "effect"> & {
+        readonly blend?: AuraBlendMode;
+        readonly size?: number | readonly [number, number];
+        readonly seed?: number;
+        readonly loop?: boolean;
+        readonly prewarm?: number;
+        readonly sprite?: AuraParticleEmitterOptions["sprite"];
+    }) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Additive thick light beam / fence strip (muse3jsparity-PRD D4): recorded
+     * with a validated quad-strip descriptor, but withheld — root has no native
+     * beam target yet, so no pass is submitted.
+     */
+    beam: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * PRD-07 §6.2 emitter surface: accepts `AuraParticleEmitterOptions` plus the
+     * legacy fields; every defined option rides the node to lowering.
+     */
+    particles: (options?: AuraParticleEmitterOptions & AuraLegacyParticleFields & Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * P2-T5 §6.2.9 trail ribbon: the node carries the ring options; lowering
+     * maps it to a `RibbonTrail` on the prd07 RibbonBatch. `target` is a runtime
+     * node id, `handle.socket(bone)` (C-19), or a callback — resolved by the
+     * production system, never by the builder.
+     */
+    trail: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * P2-T5 §6.2.10 / PRD 14 §8.9 light cone: open additive cone mesh attached to
+     * a spot light (or free-standing via `position`/`direction`), depth-write
+     * off, axial + radial falloff, soft depth.
+     */
+    lightCone: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * P2-T5 aurora ribbon (PRD 14 §8.2 geometry/fragment): an animated curtain —
+     * a ribbon strip whose fragment adds curtain fold + scrolling shimmer.
+     */
+    auroraRibbon: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * P2-T5 §6.2.11 mesh particles: instanced one-mesh draw (primitive or
+     * single-primitive GLB) with CPU sim — gravity, drag, spin, ground bounce,
+     * sleep. Transforms come from MeshParticleBatch, never
+     * `createProductionInstanceTransforms` (E17 regression guard).
+     */
+    meshParticles: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * P2-T5 fog volume: a bounded density box for the volumetric path — distinct
+     * from scene `fog`/`volumetric-fog` (global). Height falloff and scattering
+     * ride through to the P4 volumetric pass.
+     */
+    fogVolume: (options?: VfxNodeOptions) => AuraNodeBuilder<AuraEffectNode>;
+};
+export {};
+//# sourceMappingURL=effects.d.ts.map

package/dist/engine/agent-api/nodes/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/effects.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,wBAAwB,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAIvG;;;;;GAKG;AACH,KAAK,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA0BxF,eAAO,MAAM,iBAAiB;IAC5B;;;;;;OAMG;oBACY,cAAc;+BAaH,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAYjE;;;;OAIG;8BACsB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;yBAa5C,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAM3D;;;OAGG;wBACgB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAU1D;;;OAGG;uCAC+B,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAOzE;;;;OAIG;6BACqB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAe/D;;;OAGG;2BACmB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;qBAe7C,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;qBAavC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAavD;;;;;;OAMG;yBACiB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG;QAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;KACxD;IAeD;;;;OAIG;qBACa,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAmBvD;;;OAGG;0BACkB,0BAA0B,GAAG,wBAAwB,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IA0BpH;;;;;OAKG;sBACc,cAAc;IAa/B;;;;OAIG;0BACkB,cAAc;IAcnC;;;OAGG;6BACqB,cAAc;IAetC;;;;;OAKG;8BACsB,cAAc;IAevC;;;;OAIG;0BACkB,cAAc;CAYlC,CAAC"}

package/dist/engine/agent-api/nodes/effects.js

@@ -0,0 +1,323 @@
+// PR 0b-1 carve-out (CONTRACTS.md §3.2) — verbatim move from agent-api/index.ts; 0 changed logic lines.
+import { AuraNodeBuilder } from "../nodes/builder.js";
+import { effects } from "../nodes/effects.composite.js";
+import { createBeamDescriptor, resolveFlipbookUv } from "../../../rendering/index.js";
+import { particles } from "./particles.js";
+import { lazyNamespace } from "../lazyNamespace.js";
+/**
+ * Lane effect kinds ("trail", "lightCone", "auroraRibbon", "meshParticles",
+ * "fogVolume") are not yet members of the shared `AuraEffectType` union
+ * (prd15-owned; union append filed as a ccr request). The runtime lowering
+ * (`EffectNodeLowering.ts`) switches on the plain string, so the cast is
+ * type-surface only — no runtime difference, flag-on or flag-off.
+ */
+function vfxEffect(kind) {
+    return kind;
+}
+/**
+ * Copy every defined PRD-07 §6.2 emitter option onto the node value so it
+ * reaches `EffectNodeLowering` on the raw spec object (AuraEffectNode carries
+ * no typed slots for the new surface yet — fields ride through as data).
+ */
+function withEmitterOptions(value, options) {
+    const target = value;
+    for (const [key, optionValue] of Object.entries(options)) {
+        if (optionValue !== undefined)
+            target[key] = optionValue;
+    }
+    return value;
+}
+export const vfxEffectBuilders = lazyNamespace(() => ({
+    /**
+     * §6.6/F-07-01 — the builder records ONLY authored fields; C-21 defaults are
+     * applied at resolve time by compiler/fog.ts under A3D_QR_VFX_FOG (a bare
+     * `effects.fog()` → height defaults; a legacy `density`-only call → exp2 +
+     * maxOpacity 1). Flag-off compile reads `?? 0.12`/`?? "#9fb7d9"` so the
+     * uniforms are unchanged.
+     */
+    fog: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: "fog",
+        ...(options.density !== undefined ? { density: options.density } : {}),
+        ...(options.color !== undefined ? { color: options.color } : {}),
+        intensity: options.intensity
+    }, options)),
+    cinematicBloom: (options = {}) => effects.bloom({
+        intensity: options.intensity ?? 0.58,
+        color: options.color ?? "#7dfcff",
+        radius: options.radius ?? 0.42,
+        threshold: options.threshold ?? 0.72,
+        antiBlowout: options.antiBlowout ?? true,
+        maxIntensity: options.maxIntensity ?? 0.92,
+        ...(options.quality !== undefined ? { quality: options.quality } : {}),
+        ...(options.softKnee !== undefined ? { softKnee: options.softKnee } : {}),
+        ...(options.shoulder !== undefined ? { shoulder: options.shoulder } : {})
+    }),
+    /**
+     * A5 volumetric fog (muse3jsparity-PRD): builds a DISTINCT "volumetric-fog"
+     * node (never plain fog) that submits the depth-aware inscatter pass plus
+     * forward GPU height-fog terms. quality "off" keeps forward exp2 fog only.
+     */
+    volumetricFog: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "volumetric-fog",
+        name: options.name ?? "volumetric fog inscatter",
+        density: options.density ?? 0.18,
+        color: options.color ?? "#6f84b9",
+        intensity: options.intensity ?? 0.7,
+        ...(options.volumetricQuality ? { volumetricQuality: options.volumetricQuality } : {}),
+        ...(options.lightPosition ? { lightPosition: options.lightPosition } : {}),
+        ...(options.heightFalloff !== undefined ? { heightFalloff: options.heightFalloff } : {}),
+        ...(options.heightReference !== undefined ? { heightReference: options.heightReference } : {})
+    }),
+    depthFog: (options = {}) => effects.fog({
+        density: options.density ?? 0.14,
+        color: options.color ?? "#7aa2d6",
+        intensity: options.intensity ?? 0.62
+    }),
+    /**
+     * Root outline node (muse3jsparity-PRD A3): native outline pass, width in
+     * pixels clamped to the device range 1-6 by the bridge.
+     */
+    outline: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "outline",
+        name: options.name ?? "outline",
+        color: options.color ?? "#ff9822",
+        width: options.width ?? 3,
+        threshold: options.threshold ?? 0.12,
+        intensity: options.intensity ?? 0.9
+    }),
+    /**
+     * Root screen-space reflections node (muse3jsparity-PRD A3): submits the
+     * native SSR pass against renderer-owned depth where available.
+     */
+    screenSpaceReflections: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "screen-space-reflections",
+        name: options.name ?? "screen space reflections",
+        intensity: options.intensity ?? 0.9
+    }),
+    /**
+     * Root depth-of-field node (muse3jsparity-PRD A3). focus is a
+     * linear-distance fraction (0 = near plane, 1 = far plane); aperture widens
+     * the focus transition band (game-tuned control, not a physical f-stop).
+     */
+    depthOfField: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "depth-of-field",
+        name: options.name ?? "depth of field",
+        focus: options.focus ?? 0.02,
+        aperture: options.aperture ?? 0.35,
+        maxBlur: options.maxBlur ?? 4,
+        intensity: options.intensity ?? 1,
+        // CCR-03-11 (PRD-03 §8.9): v2 metric fields pass through to the bridge.
+        ...(options.focusDistance !== undefined ? { focusDistance: options.focusDistance } : {}),
+        ...(options.fStop !== undefined ? { fStop: options.fStop } : {}),
+        ...(options.focalLength !== undefined ? { focalLength: options.focalLength } : {}),
+        postAuthored: options.postAuthored ?? Object.keys(options).filter((key) => key !== "postAuthored")
+    }),
+    /**
+     * Root motion-blur node: renderer-owned GPU velocity for opaque rigid geometry.
+     * Unsupported deforming/transparent/instanced geometry emits a named warning.
+     */
+    motionBlur: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "motion-blur",
+        name: options.name ?? "motion blur",
+        intensity: options.intensity ?? 0.5,
+        // CCR-03-11 (PRD-03 §8.8): carry the v2-executed fields into the node bag;
+        // the v2 bridge reads shutter/maxBlur/samples/tileSize/timeScale here.
+        ...(options.shutter !== undefined ? { shutter: options.shutter } : {}),
+        ...(options.maxBlur !== undefined ? { maxBlur: options.maxBlur } : {}),
+        ...(options.samples !== undefined ? { samples: options.samples } : {}),
+        ...(options.tileSize !== undefined ? { tileSize: options.tileSize } : {}),
+        ...(options.timeScale !== undefined ? { timeScale: options.timeScale } : {}),
+        postAuthored: options.postAuthored ?? Object.keys(options).filter((key) => key !== "postAuthored")
+    }),
+    rain: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "rain",
+        intensity: options.intensity ?? 0.4,
+        density: options.density ?? 0.72,
+        color: options.color ?? "#bcd7ff",
+        speed: options.speed ?? 1,
+        wind: options.wind ?? [-0.32, -5.4, -0.16],
+        particleCount: options.particleCount,
+        splashes: options.splashes ?? true,
+        mist: options.mist ?? true
+    }),
+    snow: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "snow",
+        intensity: options.intensity ?? 0.4,
+        density: options.density ?? 0.68,
+        color: options.color ?? "#e8f1ff",
+        speed: options.speed ?? 1,
+        wind: options.wind ?? [-0.85, -1.1, -0.22],
+        particleCount: options.particleCount,
+        splashes: options.splashes ?? false,
+        mist: options.mist ?? true
+    }),
+    /**
+     * Flipbook explosion/muzzle-flash sprite sheet (muse3jsparity-PRD D4).
+     * Under A3D_QR_VFX it draws through the particle pass: one upright sprite
+     * of world `size`, frame = age · `frameRate` over `spriteColumns ×
+     * spriteRows` (wrapping unless `loop: false`), sampling the built-in
+     * seeded `fireball` sheet. `prewarm` starts the sprite that many seconds in.
+     */
+    flipbook: (options = {}) => {
+        const columns = options.spriteColumns ?? 4;
+        const rows = options.spriteRows ?? 4;
+        resolveFlipbookUv(0, columns, rows);
+        return new AuraNodeBuilder(withEmitterOptions({
+            kind: "effect",
+            effect: "flipbook-sprite",
+            name: options.name ?? "flipbook explosion sprite",
+            intensity: options.intensity ?? 1,
+            color: options.color ?? "#ffb347",
+            spriteColumns: columns,
+            spriteRows: rows,
+            frameRate: options.frameRate ?? 24
+        }, options));
+    },
+    /**
+     * Additive thick light beam / fence strip (muse3jsparity-PRD D4): recorded
+     * with a validated quad-strip descriptor, but withheld — root has no native
+     * beam target yet, so no pass is submitted.
+     */
+    beam: (options = {}) => {
+        const descriptor = createBeamDescriptor({
+            from: options.from ?? [0, 1, 0],
+            to: options.to ?? [0, 1, -4],
+            ...(options.widthWorld !== undefined ? { widthWorld: options.widthWorld } : {}),
+            ...(options.segmentCount !== undefined ? { segmentCount: options.segmentCount } : {})
+        });
+        return new AuraNodeBuilder({
+            kind: "effect",
+            effect: "light-beam",
+            name: options.name ?? "additive light beam",
+            intensity: options.intensity ?? 0.9,
+            color: options.color ?? "#9fd8ff",
+            from: [...descriptor.from],
+            to: [...descriptor.to],
+            widthWorld: descriptor.widthWorld,
+            segmentCount: descriptor.segmentCount
+        });
+    },
+    /**
+     * PRD-07 §6.2 emitter surface: accepts `AuraParticleEmitterOptions` plus the
+     * legacy fields; every defined option rides the node to lowering.
+     */
+    particles: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: "particles",
+        name: options.name ?? `${options.emitter ?? "fountain"} particle system`,
+        intensity: options.intensity ?? 0.8,
+        density: options.density ?? 1,
+        color: options.color ?? "#7dfcff",
+        speed: options.speed ?? 1,
+        particleCount: options.particleCount ?? 2400,
+        emitter: options.emitter ?? "fountain",
+        radius: options.radius ?? 1.15,
+        height: options.height ?? 2.4,
+        emissionRate: options.emissionRate,
+        gravity: options.gravity,
+        groundCollision: options.groundCollision,
+        lifetimeColorRamp: options.lifetimeColorRamp,
+        materialMode: options.materialMode ?? (options.emitter === "fountain" ? "additive-glow" : "soft-alpha"),
+        texturedBillboard: options.texturedBillboard ?? true,
+        sizeOverLife: options.sizeOverLife ?? [0.35, 1, 0.58],
+        alphaOverLife: options.alphaOverLife ?? [0, 0.92, 0],
+        velocityOverLife: options.velocityOverLife ?? [1, 0.82, 0.28],
+        turbulence: options.turbulence ?? 0.16,
+        noise: options.noise ?? 0.22
+    }, options)),
+    /**
+     * P2-T5 §6.2.9 trail ribbon: the node carries the ring options; lowering
+     * maps it to a `RibbonTrail` on the prd07 RibbonBatch. `target` is a runtime
+     * node id, `handle.socket(bone)` (C-19), or a callback — resolved by the
+     * production system, never by the builder.
+     */
+    trail: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: vfxEffect("trail"),
+        name: options.name ?? "trail ribbon",
+        color: options.color ?? "#7dfcff",
+        intensity: options.intensity ?? 1,
+        width: options.width ?? 0.3,
+        maxPoints: options.maxPoints ?? 48,
+        minVertexDistance: options.minVertexDistance ?? 0.05,
+        orientation: options.orientation ?? "camera"
+    }, options)),
+    /**
+     * P2-T5 §6.2.10 / PRD 14 §8.9 light cone: open additive cone mesh attached to
+     * a spot light (or free-standing via `position`/`direction`), depth-write
+     * off, axial + radial falloff, soft depth.
+     */
+    lightCone: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: vfxEffect("lightCone"),
+        name: options.name ?? "light cone",
+        color: options.color ?? "#ffe9b0",
+        intensity: options.intensity ?? 1,
+        position: options.position ?? [0, 0, 0],
+        direction: options.direction ?? [0, -1, 0],
+        length: options.length ?? 6,
+        coneAngle: options.coneAngle ?? 0.35,
+        softness: options.softness ?? 0.4
+    }, options)),
+    /**
+     * P2-T5 aurora ribbon (PRD 14 §8.2 geometry/fragment): an animated curtain —
+     * a ribbon strip whose fragment adds curtain fold + scrolling shimmer.
+     */
+    auroraRibbon: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: vfxEffect("auroraRibbon"),
+        name: options.name ?? "aurora ribbon",
+        color: options.color ?? "#54f0a8",
+        colorTop: options.colorTop ?? "#7a5cff",
+        intensity: options.intensity ?? 1.4,
+        width: options.width ?? 12,
+        height: options.height ?? 8,
+        segments: options.segments ?? 96,
+        sway: options.sway ?? 1,
+        shimmer: options.shimmer ?? 0.6
+    }, options)),
+    /**
+     * P2-T5 §6.2.11 mesh particles: instanced one-mesh draw (primitive or
+     * single-primitive GLB) with CPU sim — gravity, drag, spin, ground bounce,
+     * sleep. Transforms come from MeshParticleBatch, never
+     * `createProductionInstanceTransforms` (E17 regression guard).
+     */
+    meshParticles: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: vfxEffect("meshParticles"),
+        name: options.name ?? "mesh particles",
+        particleCount: options.particleCount ?? 32,
+        color: options.color ?? "#b0a89a",
+        gravity: options.gravity ?? -9.8,
+        drag: options.drag ?? 0.1,
+        spin: options.spin ?? 1,
+        groundBounce: options.groundBounce ?? 0.35,
+        castShadow: options.castShadow ?? false,
+        mesh: options.mesh ?? "tetrahedron"
+    }, options)),
+    /**
+     * P2-T5 fog volume: a bounded density box for the volumetric path — distinct
+     * from scene `fog`/`volumetric-fog` (global). Height falloff and scattering
+     * ride through to the P4 volumetric pass.
+     */
+    fogVolume: (options = {}) => new AuraNodeBuilder(withEmitterOptions({
+        kind: "effect",
+        effect: vfxEffect("fogVolume"),
+        name: options.name ?? "fog volume",
+        color: options.color ?? "#9fb7d9",
+        density: options.density ?? 0.25,
+        position: options.position ?? [0, 0, 0],
+        size: options.size ?? [8, 4, 8],
+        scatteringAnisotropy: options.scatteringAnisotropy ?? 0.3,
+        heightFalloff: options.heightFalloff ?? 0.5
+    }, options)),
+}));
+//# sourceMappingURL=effects.js.map

package/dist/engine/agent-api/nodes/effects.js.map

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

package/dist/engine/agent-api/nodes/effects.lighting.d.ts

@@ -0,0 +1,17 @@
+import type { AuraEffectNode } from "../index.js";
+import { AuraNodeBuilder } from "../index.js";
+export interface AuraContactShadowOptions {
+    readonly length?: number;
+    readonly thickness?: number;
+    readonly steps?: 8 | 12 | 16;
+    readonly intensity?: number;
+    readonly lights?: "sun" | "shadowed";
+}
+/** Extra fields ride on the effect node; consumed by the prd02 C-36 handler. */
+export interface AuraContactShadowsNode extends AuraEffectNode {
+    readonly contactShadows: Required<AuraContactShadowOptions>;
+}
+export declare const lightingEffectBuilders: {
+    readonly contactShadows: (options?: AuraContactShadowOptions) => AuraNodeBuilder<AuraEffectNode>;
+};
+//# sourceMappingURL=effects.lighting.d.ts.map

package/dist/engine/agent-api/nodes/effects.lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.lighting.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/effects.lighting.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,wBAAwB,CAAC,CAAC;CAC7D;AAED,eAAO,MAAM,sBAAsB;wCACP,wBAAwB;CAY1C,CAAC"}

package/dist/engine/agent-api/nodes/effects.lighting.js

@@ -0,0 +1,18 @@
+// PRD-02 Phase 2 — `effects.contactShadows` (§7 builder surface, C-10).
+// `effect: "contact-shadows"` is an additive AuraEffectType member (CCR-02-2);
+// the runtime node carries it verbatim via a cast until the union ships.
+import { AuraNodeBuilder } from "../index.js";
+export const lightingEffectBuilders = {
+    contactShadows: (options = {}) => new AuraNodeBuilder({
+        kind: "effect",
+        effect: "contact-shadows",
+        contactShadows: {
+            length: options.length ?? 0.25,
+            thickness: options.thickness ?? 0.05,
+            steps: options.steps ?? 12,
+            intensity: options.intensity ?? 1,
+            lights: options.lights ?? "sun"
+        }
+    })
+};
+//# sourceMappingURL=effects.lighting.js.map

package/dist/engine/agent-api/nodes/effects.lighting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.lighting.js","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/effects.lighting.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,yEAAyE;AAGzE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAe9C,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,cAAc,EAAE,CAAC,UAAoC,EAAE,EAAE,EAAE,CACzD,IAAI,eAAe,CAAiB;QAClC,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,iBAAmC;QAC3C,cAAc,EAAE;YACd,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;YAC9B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI;YACpC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;YAC1B,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,CAAC;YACjC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;SAChC;KACgB,CAAC;CACd,CAAC"}

package/dist/engine/agent-api/nodes/effects.post.d.ts

@@ -0,0 +1,44 @@
+import type { AuraEffectNode } from "../nodes/types.js";
+import { AuraNodeBuilder } from "../nodes/builder.js";
+/**
+ * Phase-3 v2 effect option fields (`vignette`, `film-grain`,
+ * `chromatic-aberration`) — `AuraEffectNode` field additions are a lane-15
+ * `nodes/types.ts` touch (qr-request filed); this local widening keeps the
+ * factories typed until the union lands.
+ */
+export interface PostV3EffectOptions extends Omit<AuraEffectNode, "kind" | "effect"> {
+    readonly smoothness?: number;
+    readonly roundness?: number;
+    readonly size?: number;
+    readonly luminanceResponse?: number;
+}
+export declare const postEffectBuilders: {
+    bloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    neonBloom: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    ambientOcclusion: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    contactOcclusion: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root color-grade node (muse3jsparity-PRD A3). contrast/saturation execute
+     * natively; exposure/shadows/highlights/lut are recorded on the node and
+     * warned (no native grade target yet — never silently accepted).
+     */
+    colorGrade: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * Root anti-alias node (muse3jsparity-PRD A3). `fxaa` executes natively;
+     * `off` submits nothing; `taa` uses renderer-owned velocity/history for opaque
+     * rigid triangles. Unsupported deforming/transparent geometry emits a named warning.
+     */
+    antiAlias: (options?: Omit<AuraEffectNode, "kind" | "effect">) => AuraNodeBuilder<AuraEffectNode>;
+    /**
+     * PRD-03 §6.9/§8.12 (Phase 3): display vignette — S10b `DISPLAY_GRADE`.
+     * `color` accepts "#rrggbb" or [r,g,b]; the bridge maps to `vignette`.
+     * (AuraEffectType/AuraEffectNode field extension is lane-15-owned —
+     * qr-request pending; the literals cast until it lands.)
+     */
+    vignette: (options?: PostV3EffectOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /** Phase 3: S12 film grain (size in px, luminanceResponse modulates the lerp). */
+    filmGrain: (options?: PostV3EffectOptions) => AuraNodeBuilder<AuraEffectNode>;
+    /** Phase 3: §8.12 radial chromatic aberration on the HDR composite (S10). */
+    chromaticAberration: (options?: PostV3EffectOptions) => AuraNodeBuilder<AuraEffectNode>;
+};
+//# sourceMappingURL=effects.post.d.ts.map

package/dist/engine/agent-api/nodes/effects.post.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.post.d.ts","sourceRoot":"","sources":["../../../../../../packages/engine/src/agent-api/nodes/effects.post.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;GAKG;AAGH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAID,eAAO,MAAM,kBAAkB;sBACZ,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;0BA2BnC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;iCAahC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;iCAcvC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAanE;;;;OAIG;2BACmB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAc7D;;;;OAIG;0BACkB,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC;IAY5D;;;;;OAKG;yBACiB,mBAAmB;IAWvC,kFAAkF;0BAC7D,mBAAmB;IAUxC,6EAA6E;oCAC9C,mBAAmB;CAQnD,CAAC"}