@aura3d/rendering 3.0.1 → 4.0.2

package/dist/vfx/RibbonPass.js

@@ -0,0 +1,108 @@
+// PRD-07 P2-T4 — ribbon draw pass. Builds each orientation group's strip
+// geometry on the CPU (RibbonBatch.buildAll) and submits one indexed draw per
+// group in the transparent queue (the "prd07.ribbons" C-01 contributor).
+import { TextureBinding } from "../TextureBinding.js";
+import { PRD07_DEPTH_SAMPLER } from "./depthSampler.js";
+import { VertexFormat } from "../VertexFormat.js";
+import { RibbonBatch, RIBBON_VERTEX_FLOATS } from "./RibbonBatch.js";
+import { resolveOutputColorSpace, resolveSceneDepth } from "./SceneDepthAdapter.js";
+import { RIBBON_SHADER_MARKER, ribbonFragmentSource, ribbonProgramKey, ribbonVertexSource } from "./shaders/ribbon.glsl.js";
+export const RIBBON_VERTEX_FORMAT = new VertexFormat([
+    { semantic: "position", components: 3, offset: 0, shaderName: "a_position" },
+    { semantic: "normal", components: 3, offset: 12, shaderName: "a_normal" },
+    { semantic: "uv", components: 2, offset: 24, shaderName: "a_uv" },
+    { semantic: "color", components: 4, offset: 32, shaderName: "a_color" }
+], RIBBON_VERTEX_FLOATS * 4);
+export class RibbonPass {
+    device;
+    programs = new Map();
+    vertexBuffer = null;
+    indexBuffer = null;
+    vertexCapacity = 0;
+    indexCapacity = 0;
+    constructor(device) {
+        this.device = device;
+    }
+    /** C-01 contributor: one queue item per populated orientation group. */
+    transparentItems(batch, ctx) {
+        const cameraPosition = ctx.camera?.position ?? [0, 0, 0];
+        const geometries = batch.buildAll(cameraPosition);
+        return geometries.map((g) => ({ sortDepth: 0, draw: () => this.drawGeometry(g, ctx) }));
+    }
+    drawGeometry(geometry, ctx) {
+        const vb = this.ensureBuffer("vertex", geometry.vertices.byteLength, this.vertexBuffer, "vb");
+        this.device.updateBuffer(vb, 0, geometry.vertices);
+        const ib = this.ensureBuffer("index", geometry.indices.byteLength, this.indexBuffer, "ib");
+        this.device.updateBuffer(ib, 0, geometry.indices);
+        const depth = resolveSceneDepth(ctx);
+        const softParticles = depth?.available === true && depth.source.texture !== null;
+        const shader = this.program({ softParticles });
+        const uniforms = new Map([
+            ["u_viewProjection", ctx.camera?.viewProjectionMatrix ?? IDENTITY_MAT4],
+            // §6.2.7 output contract (same as particles/beams): linear into HDR.
+            ["u_outputColorSpace", resolveOutputColorSpace(ctx) === "srgb" ? 1 : 0]
+        ]);
+        if (softParticles && depth) {
+            uniforms.set("u_sceneDepth", new TextureBinding({ name: "u_sceneDepth", texture: depth.source.texture, sampler: PRD07_DEPTH_SAMPLER }));
+            uniforms.set("u_depthLinearize", [depth.source.linearize.near, depth.source.linearize.far, depth.source.linearize.orthographic ? 1 : 0, 0]);
+        }
+        this.device.draw({
+            label: `prd07.ribbons.${geometry.orientation}`,
+            topology: "triangles",
+            vertexBuffer: vb,
+            vertexFormat: RIBBON_VERTEX_FORMAT,
+            vertexCount: geometry.vertexCount,
+            indexBuffer: ib,
+            indexType: "uint32",
+            indexCount: geometry.indices.length,
+            shader,
+            uniforms,
+            renderState: RIBBON_RENDER_STATE
+        });
+    }
+    ensureBuffer(usage, bytes, existing, which) {
+        const capacity = which === "vb" ? this.vertexCapacity : this.indexCapacity;
+        if (existing && capacity >= bytes)
+            return existing;
+        const next = Math.max(bytes, capacity * 2 || 0, 4096);
+        existing?.dispose();
+        const buffer = this.device.createBuffer(usage, next);
+        if (which === "vb") {
+            this.vertexBuffer = buffer;
+            this.vertexCapacity = next;
+        }
+        else {
+            this.indexBuffer = buffer;
+            this.indexCapacity = next;
+        }
+        return buffer;
+    }
+    program(defines) {
+        const key = ribbonProgramKey(defines);
+        let shader = this.programs.get(key);
+        if (!shader) {
+            shader = this.device.createShaderProgram({
+                label: key,
+                vertex: ribbonVertexSource(),
+                fragment: ribbonFragmentSource(defines),
+                marker: RIBBON_SHADER_MARKER
+            });
+            this.programs.set(key, shader);
+        }
+        return shader;
+    }
+    dispose() {
+        this.vertexBuffer?.dispose();
+        this.indexBuffer?.dispose();
+        this.programs.clear();
+    }
+}
+const IDENTITY_MAT4 = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+const RIBBON_RENDER_STATE = {
+    depthTest: true,
+    depthWrite: false,
+    cullMode: "none",
+    blend: true,
+    depthCompare: "less-equal"
+};
+//# sourceMappingURL=RibbonPass.js.map

package/dist/vfx/RibbonPass.js.map

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

package/dist/vfx/SceneDepthAdapter.d.ts

@@ -0,0 +1,28 @@
+import { type FrameContributorContext, type SceneDepthSource } from "../contracts/frameGraph.js";
+import { Texture } from "../Texture.js";
+/** Test hook. */
+export declare function resetSceneDepthAdapterReports(): void;
+export interface ResolvedSceneDepth {
+    readonly source: SceneDepthSource;
+    readonly available: boolean;
+    /** Non-null when the caller should emit a once-per-session degradation note. */
+    readonly pendingNote: "SOFT_DEPTH_PENDING" | "SOFT_DEPTH_INVALID_SOURCE" | null;
+}
+/**
+ * #868: lane 01's FrameGraph publishes `aura.scene.depth.copy` as the copy
+ * RenderTarget (depth lives in its `depthTexture`), not as a Texture. Binding
+ * the target itself as a sampler source crashed `getTextureHandle` (reading
+ * `mipLevels.length` of a RenderTarget) under `$ALL`. Accept a Texture or a
+ * RenderTarget with a sampleable `depthTexture`; anything else is rejected so
+ * the caller degrades to hard particles with a C-36 note instead of throwing.
+ */
+export declare function sceneDepthCopyTexture(published: unknown): Texture | null;
+export declare function resolveSceneDepth(ctx: FrameContributorContext): ResolvedSceneDepth;
+/**
+ * §6.2.7 output encoding: "linear" when the frame renders into an HDR target
+ * (postprocess on), else the legacy "srgb" encode. PRD 01 publishes the
+ * decision on the blackboard as `prd01.outputColorSpace` when postprocess is
+ * active; absent the key the legacy path applies (the flag-off convention).
+ */
+export declare function resolveOutputColorSpace(ctx: FrameContributorContext): "linear" | "srgb";
+//# sourceMappingURL=SceneDepthAdapter.d.ts.map

package/dist/vfx/SceneDepthAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneDepthAdapter.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/SceneDepthAdapter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmB,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/G,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAMrC,iBAAiB;AACjB,wBAAgB,6BAA6B,IAAI,IAAI,CAGpD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,2BAA2B,GAAG,IAAI,CAAC;CACjF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAOxE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,uBAAuB,GAAG,kBAAkB,CA4BlF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,uBAAuB,GAAG,QAAQ,GAAG,MAAM,CAGvF"}

package/dist/vfx/SceneDepthAdapter.js

@@ -0,0 +1,70 @@
+// PRD-07 P1-T10 — scene-depth adapter over the C-01 context field.
+// Returns the real depth source when PRD 01 provides it; while the stub reports
+// `available: false`, soft depth is off and SOFT_DEPTH_PENDING is reported once.
+import { FRAME_RESOURCES } from "../contracts/frameGraph.js";
+import { Texture } from "../Texture.js";
+let softDepthPendingReported = false;
+let softDepthInvalidReported = false;
+/** Test hook. */
+export function resetSceneDepthAdapterReports() {
+    softDepthPendingReported = false;
+    softDepthInvalidReported = false;
+}
+/**
+ * #868: lane 01's FrameGraph publishes `aura.scene.depth.copy` as the copy
+ * RenderTarget (depth lives in its `depthTexture`), not as a Texture. Binding
+ * the target itself as a sampler source crashed `getTextureHandle` (reading
+ * `mipLevels.length` of a RenderTarget) under `$ALL`. Accept a Texture or a
+ * RenderTarget with a sampleable `depthTexture`; anything else is rejected so
+ * the caller degrades to hard particles with a C-36 note instead of throwing.
+ */
+export function sceneDepthCopyTexture(published) {
+    if (published instanceof Texture)
+        return published.disposed ? null : published;
+    if (published !== null && typeof published === "object") {
+        const target = published;
+        if (target.disposed !== true && target.depthTexture instanceof Texture && !target.depthTexture.disposed)
+            return target.depthTexture;
+    }
+    return null;
+}
+export function resolveSceneDepth(ctx) {
+    // T0-34 FIX-softdepth-feedback: never bind ctx.sceneDepth — it is the LIVE
+    // forward depth attachment, still bound while particles draw into the same
+    // target (WebGL feedback loop, INVALID_OPERATION). Only the published copy
+    // (aura.scene.depth.copy, produced by lane 01/10's scene-copy pass) is safe
+    // to sample. Without it, soft depth degrades to hard particles with a
+    // one-shot C-36 note.
+    const published = ctx.blackboard.get(FRAME_RESOURCES.sceneDepthCopy);
+    const copy = sceneDepthCopyTexture(published);
+    if (copy) {
+        const source = {
+            texture: copy,
+            linearize: ctx.sceneDepth.linearize,
+            available: true
+        };
+        return { source, available: true, pendingNote: null };
+    }
+    if (published !== undefined && published !== null) {
+        // Published but not sampleable: fail closed (hard particles) and say so once.
+        const note = softDepthInvalidReported ? null : "SOFT_DEPTH_INVALID_SOURCE";
+        softDepthInvalidReported = true;
+        return { source: ctx.sceneDepth, available: false, pendingNote: note };
+    }
+    if (!softDepthPendingReported) {
+        softDepthPendingReported = true;
+        return { source: ctx.sceneDepth, available: false, pendingNote: "SOFT_DEPTH_PENDING" };
+    }
+    return { source: ctx.sceneDepth, available: false, pendingNote: null };
+}
+/**
+ * §6.2.7 output encoding: "linear" when the frame renders into an HDR target
+ * (postprocess on), else the legacy "srgb" encode. PRD 01 publishes the
+ * decision on the blackboard as `prd01.outputColorSpace` when postprocess is
+ * active; absent the key the legacy path applies (the flag-off convention).
+ */
+export function resolveOutputColorSpace(ctx) {
+    const published = ctx.blackboard.get("prd01.outputColorSpace");
+    return published === "linear" ? "linear" : "srgb";
+}
+//# sourceMappingURL=SceneDepthAdapter.js.map

package/dist/vfx/SceneDepthAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneDepthAdapter.js","sourceRoot":"","sources":["../../../../../packages/rendering/src/vfx/SceneDepthAdapter.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,gFAAgF;AAChF,iFAAiF;AAEjF,OAAO,EAAE,eAAe,EAAuD,MAAM,yBAAyB,CAAC;AAC/G,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAGrC,IAAI,wBAAwB,GAAG,KAAK,CAAC;AACrC,IAAI,wBAAwB,GAAG,KAAK,CAAC;AAErC,iBAAiB;AACjB,MAAM,UAAU,6BAA6B;IAC3C,wBAAwB,GAAG,KAAK,CAAC;IACjC,wBAAwB,GAAG,KAAK,CAAC;AACnC,CAAC;AASD;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAkB;IACtD,IAAI,SAAS,YAAY,OAAO;QAAE,OAAO,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/E,IAAI,SAAS,KAAK,IAAI,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,SAAkC,CAAC;QAClD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,YAAY,YAAY,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ;YAAE,OAAO,MAAM,CAAC,YAAY,CAAC;IACtI,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAA4B;IAC5D,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,sEAAsE;IACtE,sBAAsB;IACtB,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,MAAM,GAAqB;YAC/B,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,SAAS;YACnC,SAAS,EAAE,IAAI;SAChB,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACxD,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QAClD,8EAA8E;QAC9E,MAAM,IAAI,GAAG,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,2BAA2B,CAAC;QAC3E,wBAAwB,GAAG,IAAI,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAC9B,wBAAwB,GAAG,IAAI,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACzF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAA4B;IAClE,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;IAC/D,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;AACpD,CAAC"}

package/dist/vfx/VfxAtlas.d.ts

@@ -0,0 +1,68 @@
+import type { Texture } from "../Texture.js";
+import type { AuraQualityTier } from "../contracts/quality.js";
+export interface VfxAtlasManifestSequence {
+    readonly page: string;
+    readonly rect: readonly [number, number, number, number];
+    readonly columns: number;
+    readonly rows: number;
+    readonly frames: number;
+    readonly fps?: number;
+    readonly loop?: boolean;
+}
+export interface VfxAtlasManifestPage {
+    readonly id: string;
+    readonly uri: string;
+    readonly size: number;
+    readonly premultiplied: boolean;
+    readonly colorSpace: "srgb" | "linear";
+}
+/** §6.9/P6-T2 — decal atlas block: albedo + tangent-normal + roughness twins per size. */
+export interface VfxAtlasManifestDecals {
+    readonly entries: Readonly<Record<string, {
+        readonly page: string;
+        readonly rect: readonly [number, number, number, number];
+    }>>;
+    readonly albedo: readonly VfxAtlasManifestPage[];
+    readonly normal: readonly VfxAtlasManifestPage[];
+    readonly roughness: readonly VfxAtlasManifestPage[];
+}
+export interface VfxAtlasManifest {
+    readonly version: 1;
+    readonly pages: readonly VfxAtlasManifestPage[];
+    readonly sequences: Readonly<Record<string, VfxAtlasManifestSequence>>;
+    readonly decals?: VfxAtlasManifestDecals;
+}
+export interface VfxAtlasSequence extends VfxAtlasManifestSequence {
+    readonly name: string;
+    readonly texture: Texture;
+}
+/** Resolved decal: atlas rects plus the three channel textures at the tier's size. */
+export interface VfxAtlasDecal {
+    readonly name: string;
+    readonly rect: readonly [number, number, number, number];
+    readonly albedo: Texture;
+    readonly normal: Texture;
+    readonly roughness: Texture;
+}
+export interface VfxAtlasOptions {
+    /** Directory containing manifest.json and the page images, e.g. "/aura-vfx/". */
+    readonly basePath: string;
+    readonly tier: AuraQualityTier;
+    readonly fetchImpl?: typeof fetch;
+    /** Decode a page URL into a Texture. The caller routes through C-16 `createAssetDecoderRegistry` for .ktx2 pages. */
+    readonly decodeTexture: (url: string, page: VfxAtlasManifestPage) => Promise<Texture>;
+    /** Called once per page when the PNG twin is used for a .ktx2 manifest entry. */
+    readonly note?: (code: "VFX_ATLAS_PNG_FALLBACK", detail: string) => void;
+}
+export declare class VfxAtlas {
+    readonly manifest: VfxAtlasManifest;
+    private readonly pages;
+    private readonly pageSizes;
+    private readonly decalTextures?;
+    private constructor();
+    static load(options: VfxAtlasOptions): Promise<VfxAtlas>;
+    sequence(name: string): VfxAtlasSequence | null;
+    /** P6-T2 — decal entry (scorch/crack/tyre-track/puddle), rect scaled to the paged channel size. */
+    decal(name: string): VfxAtlasDecal | null;
+}
+//# sourceMappingURL=VfxAtlas.d.ts.map

package/dist/vfx/VfxAtlas.d.ts.map

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

package/dist/vfx/VfxAtlas.js

@@ -0,0 +1,106 @@
+// PRD-07 P1-T11 — VfxAtlas: loads the lane's vfx manifest.json and its pages.
+// KTX2 pages are paged through the C-16 asset decoder registry when a
+// `decodeKtx2` hook is supplied; on `AssetDecoderUnavailable` (or a missing
+// transcoder) the PNG twin loads instead and `VFX_ATLAS_PNG_FALLBACK` is
+// reported once per page.
+function isDecoderUnavailable(error) {
+    return error instanceof Error && error.name === "AssetDecoderUnavailable";
+}
+export class VfxAtlas {
+    manifest;
+    pages;
+    pageSizes;
+    decalTextures;
+    constructor(manifest, pages, pageSizes, decalTextures) {
+        this.manifest = manifest;
+        this.pages = pages;
+        this.pageSizes = pageSizes;
+        this.decalTextures = decalTextures;
+    }
+    static async load(options) {
+        const fetcher = options.fetchImpl ?? fetch;
+        const basePath = options.basePath.endsWith("/") ? options.basePath : `${options.basePath}/`;
+        const manifestResponse = await fetcher(`${basePath}manifest.json`);
+        if (!manifestResponse.ok)
+            throw new Error(`VFX_ATLAS_MANIFEST_MISSING:${manifestResponse.status}`);
+        const manifest = (await manifestResponse.json());
+        const want2k = options.tier === "high" || options.tier === "ultra";
+        const pages = new Map();
+        const pageSizes = new Map();
+        for (const page of manifest.pages) {
+            const primary = want2k === page.size >= 2048;
+            if (!primary && manifest.pages.length > 1)
+                continue; // only the tier's page is paged in
+            const url = `${basePath}${page.uri}`;
+            try {
+                pages.set(page.id, await options.decodeTexture(url, page));
+            }
+            catch (error) {
+                if (!(page.uri.endsWith(".ktx2") && isDecoderUnavailable(error)))
+                    throw error;
+                const pngUrl = url.replace(/\.ktx2$/, ".png");
+                options.note?.("VFX_ATLAS_PNG_FALLBACK", `${page.uri} → ${page.uri.replace(/\.ktx2$/, ".png")}`);
+                pages.set(page.id, await options.decodeTexture(pngUrl, { ...page, uri: page.uri.replace(/\.ktx2$/, ".png") }));
+            }
+            pageSizes.set(page.id, page.size);
+        }
+        // P6-T2 decal channels: page the tier-size variant of each channel.
+        let decalTextures;
+        if (manifest.decals) {
+            const pick = async (channel) => {
+                const page = channel.find((candidate) => (candidate.size >= 2048) === want2k) ?? channel[0];
+                if (!page)
+                    return null;
+                pageSizes.set(page.id, page.size);
+                return options.decodeTexture(`${basePath}${page.uri}`, page);
+            };
+            const [albedo, normal, roughness] = await Promise.all([
+                pick(manifest.decals.albedo),
+                pick(manifest.decals.normal),
+                pick(manifest.decals.roughness)
+            ]);
+            if (albedo && normal && roughness)
+                decalTextures = { albedo, normal, roughness };
+        }
+        return new VfxAtlas(manifest, pages, pageSizes, decalTextures);
+    }
+    sequence(name) {
+        const entry = this.manifest.sequences[name];
+        if (!entry)
+            return null;
+        const texture = this.pages.get(entry.page);
+        if (texture)
+            return { name, texture, ...entry };
+        // Tier twin: the entry's page wasn't paged; scale the rect onto the page
+        // that was (bake emits a half-size twin with identical layout).
+        if (this.pages.size !== 1)
+            return null;
+        const [twinId, twinTexture] = [...this.pages.entries()][0];
+        const declaredSize = this.manifest.pages.find((page) => page.id === entry.page)?.size;
+        const twinSize = this.pageSizes.get(twinId);
+        if (!declaredSize || !twinSize)
+            return null;
+        const scale = twinSize / declaredSize;
+        const [x, y, w, h] = entry.rect;
+        return { name, texture: twinTexture, ...entry, rect: [x * scale, y * scale, w * scale, h * scale] };
+    }
+    /** P6-T2 — decal entry (scorch/crack/tyre-track/puddle), rect scaled to the paged channel size. */
+    decal(name) {
+        const decals = this.manifest.decals;
+        const entry = decals?.entries[name];
+        if (!decals || !entry || !this.decalTextures)
+            return null;
+        const declaredSize = decals.albedo.find((page) => page.id === entry.page)?.size;
+        const pagedSize = this.pageSizes.get(entry.page) ?? declaredSize;
+        const scale = declaredSize && pagedSize ? pagedSize / declaredSize : 1;
+        const [x, y, w, h] = entry.rect;
+        return {
+            name,
+            rect: [x * scale, y * scale, w * scale, h * scale],
+            albedo: this.decalTextures.albedo,
+            normal: this.decalTextures.normal,
+            roughness: this.decalTextures.roughness
+        };
+    }
+}
+//# sourceMappingURL=VfxAtlas.js.map

package/dist/vfx/VfxAtlas.js.map

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

package/dist/vfx/contributors.d.ts

@@ -0,0 +1,73 @@
+import type { RenderDevice } from "../RenderDevice.js";
+import { type FrameContributor, type FrameContributorContext } from "../contracts/frameGraph.js";
+import type { RenderSource } from "../contracts/renderSource.js";
+import type { ParticleRenderHook } from "../contracts/particles.js";
+import type { AuraSkySpecLike } from "../contracts/atmosphere.js";
+import { ParticleBatchPass, type ParticlePassDiagnostics } from "./ParticleBatchPass.js";
+import { BeamPass, type BeamDrawSpec } from "./BeamPass.js";
+import { MeshParticlePass, type MeshParticleFeed } from "./MeshParticlePass.js";
+import { RibbonBatch } from "./RibbonBatch.js";
+import { RibbonPass } from "./RibbonPass.js";
+import type { DecalBatch } from "./DecalBatch.js";
+import { type GpuSimSpec } from "./ParticleGpuSim.js";
+/** §8.3 GPU sim request published per emitter whose sim lowered to "gpu". */
+export interface GpuSimRequest {
+    readonly nodeId: string;
+    readonly batchKey: string;
+    readonly emitCount: number;
+    readonly spec: GpuSimSpec;
+}
+/** What the engine-side effects system publishes on the RenderSource. */
+export interface VfxFrameSource {
+    /** Upsert batches + write this frame's live instances through the hook. */
+    feed(hook: ParticleRenderHook): void;
+    /** §8.3: emitters requesting a ParticleGpuSim (P5-T1). */
+    gpuSimFeed?(): readonly GpuSimRequest[];
+    /** Called once after the contributor collected queue items, with observed stats. */
+    afterDraw?(diagnostics: ParticlePassDiagnostics): void;
+    /** P2-T7 transient lights — read by the prd07.lights contributor in collect. */
+    lightsFeed?(): readonly import("../LightCollector.js").CollectedLight[];
+    /** §6.2.9 ribbon ring owned by the engine system; prd07.ribbons draws it. */
+    ribbonFeed?(): RibbonBatch;
+    /** §6.2.10 beam-family draw specs for prd07.beams. */
+    beamFeed?(): readonly BeamDrawSpec[];
+    /** §6.2.11 instanced mesh batches for prd07.mesh. */
+    meshFeed?(): readonly MeshParticleFeed[];
+    /** §6.9 merged decal ring for prd07.decals (P6-T1). */
+    decalFeed?(): DecalBatch;
+}
+/** What the engine-side atmosphere state publishes on the RenderSource. */
+export interface AtmosphereFrameSource {
+    readonly sky: AuraSkySpecLike | null;
+    /** P3-T6 — live state + sky-change listener for SkyCaptureAdapter wiring. */
+    state?(): {
+        readonly sky: unknown | null;
+    };
+    onSkyChanged?(listener: () => void): (() => void) | void;
+}
+export interface Prd07FrameSource extends RenderSource {
+    readonly vfx?: VfxFrameSource | null;
+    readonly atmosphere?: AtmosphereFrameSource | null;
+}
+export declare function particlePassFor(device: RenderDevice): ParticleBatchPass;
+export declare function ribbonPassFor(device: RenderDevice): RibbonPass;
+export declare function beamPassFor(device: RenderDevice): BeamPass;
+export declare function meshPassFor(device: RenderDevice): MeshParticlePass;
+/** Last measured "particles" scope ms (feed + draws); null until a frame ran. */
+export declare function lastParticleUpdateMs(): number | null;
+export declare const decalsContributor: FrameContributor;
+export declare function prd07OpaqueColorResource(ctx: FrameContributorContext): string;
+/** Reads for a pass that samples the scene-depth copy (v2 path only). */
+export declare function prd07DepthCopyReads(ctx: FrameContributorContext): readonly string[];
+/** Feed one measured volumetric-GPU-ms sample for `device`. */
+export declare function notePrd07VolumetricGpuMs(device: RenderDevice, ms: number): void;
+/** C-31 atmosphere scope of the §18 tier envelope: 1.2ms medium / 2.0ms high;
+ *  WebDriver (software GL) pins the tight 0.6ms cap. */
+export declare function froxelBudgetMs(tier: {
+    readonly volumetricFog?: string | null;
+}): number;
+/** EWMA-with-hysteresis gate — true while the measured cost exceeds `budgetMs`. */
+export declare function prd07VolumetricCostFallback(device: RenderDevice, budgetMs: number): boolean;
+/** Idempotent lane registration (P1-T1): safe on repeated barrel imports. */
+export declare function registerPrd07Contributors(): void;
+//# sourceMappingURL=contributors.d.ts.map

package/dist/vfx/contributors.d.ts.map

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