@aura3d/engine 3.0.0 → 4.0.0

package/dist/engine/production-runtime/effects/ProductionEffectSystem.js

@@ -0,0 +1,827 @@
+// PRD-07 P1-T14 — per-app effect runtime (PRD-07 §6.3).
+// Lowers every effect node in the scene to a CpuEmitter (or a pass-through
+// record for non-particle kinds), steps sim on app.onFrame, feeds the C-20
+// hook during the collect phase, and reports observed draws into
+// EffectDiagnostics after the transparent phase.
+import { Texture } from "../../../rendering/index.js";
+import { QUALITY_TIERS } from "../../../rendering/contracts/index.js";
+import { MeshParticleBatch, RibbonBatch, RibbonTrail, DecalBatch, DECAL_TIER_CAP, decalQuadGeometry, ribbonStripToDecalGeometry, PARTICLE_GPU_BUDGET_MS } from "../../../rendering/index.js";
+import { createEmitter, stepEmitter, writeEmitterInstances } from "./CpuEmitter.js";
+import { proceduralFireballSheet } from "./FlipbookAtlas.js";
+import { lowerEffectNode, srgbChannelToLinear } from "./EffectNodeLowering.js";
+import { EffectDiagnostics } from "./EffectDiagnostics.js";
+import { LiveAtmosphere } from "./LiveAtmosphere.js";
+import { TransientLightPool } from "./TransientLightPool.js";
+let sharedSoftDot = null;
+/** 1×1 white fallback atlas; the particle program detects it and draws the analytic soft-dot. */
+export function softDotTexture() {
+    if (!sharedSoftDot) {
+        sharedSoftDot = new Texture({ width: 1, height: 1, label: "a3d-soft-dot", data: new Uint8Array([255, 255, 255, 255]) });
+    }
+    return sharedSoftDot;
+}
+const flipbookTextures = new Map();
+/** Built-in `fireball` sheet texture for a flipbook emitter (sRGB, straight alpha; cached per grid + seed). */
+function flipbookTexture(fb) {
+    const sheet = proceduralFireballSheet(fb.columns ?? 1, fb.rows ?? 1, fb.seed ?? 0);
+    const key = `${sheet.columns}x${sheet.rows}:${(fb.seed ?? 0) >>> 0}`;
+    let texture = flipbookTextures.get(key);
+    if (!texture) {
+        texture = new Texture({ width: sheet.width, height: sheet.height, colorSpace: "srgb", label: `a3d-flipbook-fireball-${key}`, data: sheet.data });
+        flipbookTextures.set(key, texture);
+    }
+    return texture;
+}
+function hexToRgb(c) {
+    if (c.startsWith("#") && c.length === 7) {
+        return [parseInt(c.slice(1, 3), 16) / 255, parseInt(c.slice(3, 5), 16) / 255, parseInt(c.slice(5, 7), 16) / 255];
+    }
+    return [1, 1, 1];
+}
+function effectColor4(node) {
+    const c = node.color;
+    if (Array.isArray(c) && c.length >= 3)
+        return [Number(c[0]), Number(c[1]), Number(c[2]), Number(c[3] ?? 1)];
+    // Hex is sRGB-encoded (three.js Color parity); beams, ribbons and mesh
+    // particles shade in linear HDR, so decode here like particles and decals.
+    if (typeof c === "string") {
+        const [r, g, b] = hexToLinearRgb(c);
+        return [r, g, b, 1];
+    }
+    return [1, 1, 1, 1];
+}
+/**
+ * Local copy of the agent-api `eulerToQuat` (XYZ half-angle formula — the
+ * default node-rotation path; importing agent-api here would cycle).
+ */
+function prd07EulerToQuat(rotation) {
+    const [x, y, z] = rotation;
+    const c1 = Math.cos(x / 2), c2 = Math.cos(y / 2), c3 = Math.cos(z / 2);
+    const s1 = Math.sin(x / 2), s2 = Math.sin(y / 2), s3 = Math.sin(z / 2);
+    return [
+        s1 * c2 * c3 + c1 * s2 * s3,
+        c1 * s2 * c3 - s1 * c2 * s3,
+        c1 * c2 * s3 + s1 * s2 * c3,
+        c1 * c2 * c3 - s1 * s2 * s3
+    ];
+}
+/** Minimal rotation quaternion taking unit vector `a` to unit vector `b`. */
+function quatFromUnitVectors(a, b) {
+    const an = Math.hypot(a[0], a[1], a[2]) || 1;
+    const bn = Math.hypot(b[0], b[1], b[2]) || 1;
+    const ax = a[0] / an, ay = a[1] / an, az = a[2] / an;
+    const bx = b[0] / bn, by = b[1] / bn, bz = b[2] / bn;
+    const dot = ax * bx + ay * by + az * bz;
+    if (dot > 0.999999)
+        return [0, 0, 0, 1];
+    if (dot < -0.999999) {
+        // 180°: pick any orthogonal axis.
+        const px = Math.abs(ax) < 0.9 ? 1 : 0;
+        const py = px === 1 ? 0 : 1;
+        const vx = ay * 0 - az * py, vy = az * px - ax * 0, vz = ax * py - ay * px;
+        const vn = Math.hypot(vx, vy, vz) || 1;
+        return [vx / vn, vy / vn, vz / vn, 0];
+    }
+    const cx = ay * bz - az * by;
+    const cy = az * bx - ax * bz;
+    const cz = ax * by - ay * bx;
+    const w = 1 + dot;
+    const n = Math.hypot(cx, cy, cz, w) || 1;
+    return [cx / n, cy / n, cz / n, w / n];
+}
+/** Decal albedo hex → linear (three.js Color parity; the decal BRDF is linear). */
+function hexToLinearRgb(c) {
+    const [r, g, b] = hexToRgb(c);
+    return [srgbChannelToLinear(r), srgbChannelToLinear(g), srgbChannelToLinear(b)];
+}
+function decalColor4(color) {
+    if (typeof color === "string") {
+        const [r, g, b] = hexToLinearRgb(color);
+        return [r, g, b, 1];
+    }
+    if (Array.isArray(color) && color.length >= 3)
+        return [Number(color[0]), Number(color[1]), Number(color[2]), Number(color[3] ?? 1)];
+    return [1, 1, 1, 1];
+}
+/**
+ * §6.9 decal → DecalBatch vertex data. `primitive: "plane"` decals become a
+ * transformed quad (`decalQuadGeometry`); `primitive: "custom"` decals keep
+ * their baked projected vertices (positions + normals + uvs + indices).
+ */
+function decalNodeGeometry(node, decal) {
+    if (node.primitive === "plane") {
+        const size = decal.size ?? [1, 1];
+        const quaternion = node.quaternion
+            ?? prd07EulerToQuat(node.rotation ?? [0, 0, 0]);
+        const position = node.position ?? [0, 0, 0];
+        return decalQuadGeometry(quaternion, position, [size[0], size[1]], decal.normalOffset ?? 0.012);
+    }
+    const geometry = node.geometry;
+    if (!geometry?.positions || !geometry.indices || geometry.positions.length === 0 || geometry.indices.length === 0)
+        return null;
+    const vertices = new Float32Array(geometry.positions.length * 8);
+    for (let i = 0; i < geometry.positions.length; i += 1) {
+        const p = geometry.positions[i];
+        const n = geometry.normals?.[i] ?? [0, 1, 0];
+        const uv = geometry.uvs?.[i] ?? [0, 0];
+        const o = i * 8;
+        vertices[o + 0] = p[0] ?? 0;
+        vertices[o + 1] = p[1] ?? 0;
+        vertices[o + 2] = p[2] ?? 0;
+        vertices[o + 3] = n[0] ?? 0;
+        vertices[o + 4] = n[1] ?? 1;
+        vertices[o + 5] = n[2] ?? 0;
+        vertices[o + 6] = uv[0] ?? 0;
+        vertices[o + 7] = uv[1] ?? 0;
+    }
+    return { vertices, indices: new Uint32Array(geometry.indices) };
+}
+/** Convert a lowered beam-family node into the pass's draw spec. */
+function beamSpec(node, nodeId) {
+    const color = effectColor4(node);
+    const top = node.colorTop !== undefined
+        ? (typeof node.colorTop === "string"
+            ? [...hexToLinearRgb(node.colorTop), 1]
+            : [Number(node.colorTop[0]), Number(node.colorTop[1]), Number(node.colorTop[2]), Number(node.colorTop[3] ?? 1)])
+        : undefined;
+    return {
+        nodeId,
+        kind: node.effect ?? "light-beam",
+        color,
+        intensity: node.intensity ?? 1,
+        ...(node.position !== undefined ? { position: node.position } : {}),
+        ...(node.from !== undefined ? { from: node.from } : {}),
+        ...(node.to !== undefined ? { to: node.to } : {}),
+        ...(node.widthWorld !== undefined ? { widthWorld: node.widthWorld } : {}),
+        ...(node.segmentCount !== undefined ? { segmentCount: node.segmentCount } : {}),
+        ...(node.direction !== undefined ? { direction: node.direction } : {}),
+        ...(node.length !== undefined ? { length: node.length } : {}),
+        ...(node.coneAngle !== undefined ? { coneAngle: node.coneAngle } : {}),
+        ...(node.softness !== undefined ? { softness: node.softness } : {}),
+        ...(node.width !== undefined ? { width: node.width } : {}),
+        ...(node.height !== undefined ? { height: node.height } : {}),
+        ...(node.segments !== undefined ? { segments: node.segments } : {}),
+        ...(node.sway !== undefined ? { sway: node.sway } : {}),
+        ...(node.shimmer !== undefined ? { shimmer: node.shimmer } : {}),
+        ...(top !== undefined ? { colorTop: top } : {})
+    };
+}
+/** Deterministic spawn for a meshParticles node at attach time. */
+function seedMeshBatch(node) {
+    const batch = new MeshParticleBatch({
+        capacity: Math.max(1, Math.round(node.particleCount ?? 32)),
+        ...(node.gravity !== undefined && typeof node.gravity === "number" ? { gravity: node.gravity } : {}),
+        ...(node.drag !== undefined ? { drag: node.drag } : {}),
+        ...(node.spin !== undefined ? { spinRate: node.spin } : {}),
+        groundY: 0,
+        restitution: node.groundBounce ?? 0.35,
+        seed: typeof node.seed === "number" ? node.seed : 0x9e3779b9
+    });
+    const origin = node.position ?? [0, 0, 0];
+    const color = effectColor4(node);
+    const count = batch.capacity;
+    const rng = mulberry32(typeof node.seed === "number" ? node.seed : 7);
+    for (let i = 0; i < count; i++) {
+        const a = rng() * Math.PI * 2;
+        const speed = 1.5 + rng() * 3;
+        batch.spawn({
+            position: [origin[0] + (rng() - 0.5) * 0.4, origin[1], origin[2] + (rng() - 0.5) * 0.4],
+            velocity: [Math.cos(a) * speed, 2.5 + rng() * 3, Math.sin(a) * speed],
+            scale: 0.08 + rng() * 0.15,
+            color,
+            spinAxis: [rng() - 0.5, rng() - 0.5, rng() - 0.5],
+            spin: (node.spin ?? 1) * (0.5 + rng()),
+            life: 3 + rng() * 2
+        });
+    }
+    return batch;
+}
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export class ProductionEffectSystem {
+    app;
+    diagnostics = new EffectDiagnostics();
+    atmosphere = new LiveAtmosphere();
+    /** C-27 tier the system budgets against (resolved by the C-38 factory). */
+    tier;
+    budgetCap;
+    culledTotal = 0;
+    emitters = new Map();
+    batchHandles = new Map();
+    groupScratch = new Map();
+    frameBatchMembers = new Map();
+    frameLive = new Map();
+    offFrame;
+    /** P2-T7 transient light pool — tier-capped flashes for the burst presets. */
+    transientLights;
+    /** §6.2.9 ribbon state — trails own the ring; the RibbonPass draws it. */
+    ribbons = new RibbonBatch();
+    trails = new Map();
+    beams = new Map();
+    /** P6 runtime decals spawned via effects.decal (drawn by DecalBatch). */
+    decalNodes = new Map();
+    meshBatches = new Map();
+    drawFeedQueue = null;
+    disposed = false;
+    time = 0;
+    skyFlagOn = false;
+    weatherFlagOn = false;
+    decalFlagOn = false;
+    /** §6.9 merged decal ring — C-27 tier cap replaces AURA_DECAL_MAX_DECALS. */
+    decals;
+    /** Last hook passed to feed — lets the host push P6-T4 GPU-ms samples in. */
+    lastHook = null;
+    /** True once a canvas render bridge publishes this system to a renderer. */
+    renderBridged = false;
+    /** A renderer frame pulled the render source since the last endFrame. */
+    renderSincePrevFrame = false;
+    constructor(app, options = {}) {
+        this.app = app;
+        // Resolved C-27 tier wins over the explicit option's fallback: callers pass
+        // app.quality.tier; "high" remains only as the unresolved default.
+        this.tier = options.tier ?? app.quality?.tier ?? "high";
+        this.decals = new DecalBatch(DECAL_TIER_CAP[this.tier]);
+        this.budgetCap = QUALITY_TIERS[this.tier].particleBudget;
+        this.transientLights = new TransientLightPool(this.tier);
+        this.rebuildFromScene();
+        this.offFrame = app.onFrame((frame) => this.frame(frame.dt));
+    }
+    /** P6-T4 — measured particle GPU ms; auto-engages the half-res path past the
+     *  tier budget (PARTICLE_GPU_BUDGET_MS). Off until a runtime measures. */
+    noteParticleGpuMs(ms) {
+        this.lastHook?.noteGpuMs?.(ms, PARTICLE_GPU_BUDGET_MS[this.tier] ?? PARTICLE_GPU_BUDGET_MS.default);
+    }
+    /**
+     * Zero-pixel accounting is per *rendered* frame. Once a canvas bridge binds
+     * this system to a renderer, sim ticks with no renderer frame in between
+     * (async WebGL mount, fixed-step substeps) are not counted; headless apps
+     * with no bridge keep counting every tick.
+     */
+    noteRenderBridgeAttached() {
+        this.renderBridged = true;
+    }
+    /** Called by the canvas bridge each time a renderer frame reads the source. */
+    noteRenderFrame() {
+        this.renderSincePrevFrame = true;
+    }
+    /** P6-T4 — force the half-res particle path on/off regardless of budget. */
+    setParticleLowRes(on) {
+        this.lastHook?.setLowResEnabled?.(on);
+    }
+    /** P3-T4 — sky nodes land on LiveAtmosphere (consumed by prd07.sky flag-on). */
+    rebuildSkyFromScene() {
+        // Grouped-effects walk: sky nodes inside visible groups count too.
+        this.walkNodes((node, visible) => {
+            if (!visible || node.kind !== "sky")
+                return;
+            const spec = node.spec;
+            if (spec && typeof spec === "object")
+                this.atmosphere.setSky(spec);
+        });
+        this.applyLegacySkyVisibility();
+    }
+    /**
+     * §6.5 — `sky.dayNight` legacy primitives are runtime-tagged
+     * `prd07.legacySky.<n>`. With `A3D_QR_VFX_SKY` on they hide through their
+     * runtime handles; flag-off the setter is never called and the frame is
+     * unchanged.
+     */
+    applyLegacySkyVisibility() {
+        if (!this.skyFlagOn || !this.app.nodes)
+            return;
+        this.hideTaggedLegacyNodes("prd07.legacySky.");
+    }
+    /** Bound by the C-38 extension factory with the app's resolved flag state. */
+    setSkyFlagOn(on) {
+        this.skyFlagOn = on;
+        this.applyLegacySkyVisibility();
+    }
+    /**
+     * §8.6/P5-T4 — `weather.precipitation`/`weather.wetGround` legacy primitives
+     * are runtime-tagged `prd07.legacyWeather.<n>`; under A3D_QR_VFX they hide
+     * through their runtime handles. Flag-off the setter is never called and
+     * the frame is bit-identical.
+     */
+    applyLegacyWeatherVisibility() {
+        if (!this.weatherFlagOn || !this.app.nodes)
+            return;
+        this.hideTaggedLegacyNodes("prd07.legacyWeather.");
+    }
+    /** Bound by the C-38 extension factory with the app's resolved flag state. */
+    setWeatherFlagOn(on) {
+        this.weatherFlagOn = on;
+        this.applyLegacyWeatherVisibility();
+    }
+    /**
+     * §6.9/P6-T1 — decal primitives are runtime-tagged `prd07.legacyDecal.<n>`.
+     * Under A3D_QR_VFX_DECALS the tag hides them through their runtime handles
+     * and DecalBatch draws them instead; flag-off the setter is never called
+     * and the forward decal path is byte-identical to today.
+     */
+    applyLegacyDecalVisibility() {
+        if (!this.decalFlagOn || !this.app.nodes)
+            return;
+        this.hideTaggedLegacyNodes("prd07.legacyDecal.");
+    }
+    /** Bound by the C-38 extension factory with the app's resolved flag state. */
+    setDecalFlagOn(on) {
+        this.decalFlagOn = on;
+        this.applyLegacyDecalVisibility();
+        // P6-T3 — surface trails move to the decal pass under the flag; the ribbon
+        // pass keeps only the camera-oriented group (no double draw).
+        this.ribbons.enabledOrientations = on ? ["camera"] : ["camera", "surface"];
+    }
+    /** Scene snapshot the last rebuild was computed from (nodes ref + version). */
+    lastSceneNodes = null;
+    lastSceneVersion = -1;
+    sceneSignature() {
+        const s = this.app.scene;
+        return { nodes: s.nodes, version: s.version ?? -1 };
+    }
+    /**
+     * Hide every runtime-tagged legacy primitive with `prefix`, including ones
+     * nested in groups (grouped-effects walk). Hidden ancestors already hide
+     * their subtree, so only visible branches are visited.
+     */
+    hideTaggedLegacyNodes(prefix) {
+        const nodes = this.app.nodes;
+        if (!nodes)
+            return;
+        this.walkNodes((node, visible) => {
+            if (!visible)
+                return;
+            const runtimeId = node.runtime?.id;
+            if (typeof runtimeId === "string" && runtimeId.startsWith(prefix))
+                nodes.get(runtimeId)?.setVisible?.(false);
+        });
+    }
+    /** Recursive scene walk — group children descend only under a visible ancestor. */
+    walkNodes(visit, nodes = this.app.scene.nodes, parentVisible = true) {
+        for (const node of nodes) {
+            const visible = parentVisible && node.visible !== false;
+            visit(node, visible);
+            if (node.children)
+                this.walkNodes(visit, node.children, visible);
+        }
+    }
+    rebuildFromScene() {
+        const sig = this.sceneSignature();
+        this.lastSceneNodes = sig.nodes;
+        this.lastSceneVersion = sig.version;
+        this.rebuildSkyFromScene();
+        this.applyLegacyDecalVisibility();
+        const fogNodes = [];
+        const fogVolumes = [];
+        this.walkNodes((node, visible) => {
+            if (!visible || node.kind !== "effect")
+                return;
+            const lowered = lowerEffectNode(node);
+            this.diagnostics.track({
+                nodeId: lowered.nodeId,
+                effect: lowered.effect,
+                consumer: lowered.consumer,
+                live: 0,
+                sim: lowered.sim,
+                softDepth: lowered.type === "emitter" ? lowered.batch.softDepth : false
+            });
+            if (lowered.type === "emitter") {
+                this.attachEmitter(lowered);
+            }
+            else {
+                this.attachNonEmitter(node, lowered);
+            }
+            if (lowered.consumer === "scene-fog") {
+                (lowered.effect === "fogVolume" ? fogVolumes : fogNodes).push(node);
+            }
+        });
+        this.atmosphere.trackFogNodes(fogNodes);
+        this.atmosphere.trackFogVolumes(fogVolumes);
+    }
+    /**
+     * Attach a lowered non-emitter node to its consumer's lane state:
+     * beam-pass kinds become draw specs, ribbon-pass trails join the
+     * RibbonBatch ring (preseeded from `path`, live points via trailPush),
+     * mesh-pass kinds own a MeshParticleBatch.
+     */
+    attachNonEmitter(node, lowered) {
+        if (lowered.consumer === "beam-pass") {
+            this.beams.set(lowered.nodeId, node);
+        }
+        else if (lowered.consumer === "ribbon-pass") {
+            const color = effectColor4(node);
+            const trail = this.ribbons.upsertTrail({
+                id: lowered.nodeId,
+                maxPoints: node.maxPoints,
+                minVertexDistance: node.minVertexDistance,
+                width: node.width,
+                color,
+                orientation: node.orientation === "surface" ? "surface" : "camera",
+                ...(node.surfaceNormal !== undefined ? { surfaceNormal: node.surfaceNormal } : {})
+            });
+            if (Array.isArray(node.path)) {
+                const points = node.path.filter((p) => Array.isArray(p) && p.length >= 3);
+                const step = points.length > 1 ? 0.02 : 0;
+                points.forEach((p, i) => trail.push([p[0] ?? 0, p[1] ?? 0, p[2] ?? 0], i * step));
+            }
+            this.trails.set(lowered.nodeId, { trail, node });
+        }
+        else if (lowered.consumer === "mesh-pass") {
+            this.meshBatches.set(lowered.nodeId, seedMeshBatch(node));
+        }
+        else if (lowered.consumer === "decal-pass") {
+            this.decalNodes.set(lowered.nodeId, node);
+        }
+        // "post"/"scene-fog"/"none" consumers have no lane state (P3/P4).
+    }
+    /** Per-frame feed: the RibbonBatch the prd07.ribbons contributor draws. */
+    ribbonFeed() {
+        return this.ribbons;
+    }
+    /** Per-frame feed: beam-family draw specs for the prd07.beams contributor. */
+    beamFeed() {
+        return [...this.beams.entries()].map(([nodeId, node]) => beamSpec(node, nodeId));
+    }
+    /** Per-frame feed: mesh batches for the prd07.mesh contributor. */
+    meshFeed() {
+        return [...this.meshBatches.entries()].map(([nodeId, batch]) => ({ nodeId, batch }));
+    }
+    /**
+     * Per-frame feed: the merged DecalBatch the prd07.decals contributor draws
+     * (§6.9). Syncs authored decal nodes (plane quads + projected customs) into
+     * the ring each call so live edits propagate; stale ids are removed.
+     */
+    decalFeed() {
+        this.syncDecals();
+        return this.decals;
+    }
+    syncDecals() {
+        const seen = new Set();
+        const nodes = (this.app.scene.nodes ?? []);
+        for (let i = 0; i < nodes.length; i += 1) {
+            const node = nodes[i];
+            if (node.kind !== "primitive")
+                continue;
+            const decal = node.decal;
+            if (!decal)
+                continue;
+            const runtimeId = node.runtime?.id;
+            const id = runtimeId ?? `decal.${i}`;
+            seen.add(id);
+            const material = (node.material ?? {});
+            const [r, g, b] = typeof material.color === "string" ? hexToLinearRgb(material.color) : [1, 1, 1];
+            const geometry = decalNodeGeometry(node, decal);
+            if (!geometry)
+                continue;
+            this.decals.upsert({
+                id,
+                pageKey: decal.textureUrl ?? material.texture?.url ?? `flat:${String(material.color ?? "#ffffff")}`,
+                blend: material.blend === "multiply" ? "multiply" : "alpha",
+                geometry,
+                color: [r, g, b, decal.baseOpacity ?? 1],
+                roughness: material.roughness ?? 0.5,
+                fade: decal.fade,
+                polygonOffset: decal.polygonOffset,
+                life: Number.POSITIVE_INFINITY
+            }, this.time);
+        }
+        // §6.9/P6-T3 — surface-oriented trails ride the decal pass with polygon
+        // offset; per-vertex color/fade baked into stride-16 vertices.
+        for (const [nodeId, binding] of this.trails) {
+            const trailId = `surface-trail.${nodeId}`;
+            if (binding.trail.options.orientation !== "surface")
+                continue;
+            const strip = this.ribbons.buildGeometry(binding.trail, [0, 0, 0]); // camera unused for surface
+            if (!strip)
+                continue;
+            seen.add(trailId);
+            this.decals.upsert({
+                id: trailId,
+                pageKey: "surface-trails",
+                blend: "alpha",
+                geometry: ribbonStripToDecalGeometry(strip),
+                polygonOffset: { factor: -2, units: -2 },
+                life: Number.POSITIVE_INFINITY
+            }, this.time);
+        }
+        // Runtime decals spawned via effects.decal — quads at their origin,
+        // facing `decal.normal` (default +Z, matching Decals.ts).
+        for (const [nodeId, node] of this.decalNodes) {
+            const d = node.decal;
+            const runtimeId = `runtime-decal.${nodeId}`;
+            if (!d)
+                continue;
+            seen.add(runtimeId);
+            const position = node.position ?? [0, 0, 0];
+            const size = d.size ?? [1, 1];
+            const normal = d.normal ?? [0, 0, 1];
+            // Quad in the decal's facing plane: quaternion from +Z to `normal`.
+            const quat = quatFromUnitVectors([0, 0, 1], normal);
+            this.decals.upsert({
+                id: runtimeId,
+                pageKey: d.textureUrl ?? `flat:${typeof d.color === "string" ? d.color : "#ffffff"}`,
+                blend: "alpha",
+                geometry: decalQuadGeometry(quat, [position[0] ?? 0, position[1] ?? 0, position[2] ?? 0], [size[0], size[1]], d.normalOffset ?? 0.012),
+                color: decalColor4(d.color),
+                roughness: 0.5,
+                fade: d.fade,
+                polygonOffset: d.polygonOffset,
+                life: d.lifetime ?? Number.POSITIVE_INFINITY
+            }, this.time);
+        }
+        // Remove slots whose nodes left the scene.
+        for (const existing of this.decals.ids()) {
+            if (!seen.has(existing))
+                this.decals.remove(existing);
+        }
+    }
+    /** Append a live trail point (target-follow / scripted motion callers). */
+    trailPush(nodeId, position, width, color) {
+        const binding = this.trails.get(nodeId);
+        if (!binding)
+            return false;
+        return binding.trail.push(position, this.time, width, color);
+    }
+    attachEmitter(lowered) {
+        const state = createEmitter(lowered.emitter);
+        const binding = {
+            lowered,
+            state,
+            scratch: new Float32Array(Math.max(64, lowered.emitter.capacity) * 16)
+        };
+        this.emitters.set(lowered.nodeId, binding);
+        return binding;
+    }
+    /** Add a transient effect-instance emitter (effects.burst/spawn). */
+    addInstance(nodeId, node) {
+        const lowered = lowerEffectNode(node);
+        this.diagnostics.track({
+            nodeId,
+            effect: lowered.effect,
+            consumer: lowered.consumer,
+            live: 0,
+            sim: lowered.sim,
+            softDepth: lowered.type === "emitter" ? lowered.batch.softDepth : false
+        });
+        if (lowered.type === "emitter") {
+            this.attachEmitter({ ...lowered, nodeId });
+        }
+        else {
+            this.attachNonEmitter(node, lowered);
+        }
+        return nodeId;
+    }
+    setInstanceOrigin(nodeId, origin) {
+        const binding = this.emitters.get(nodeId);
+        if (binding) {
+            binding.state.desc = { ...binding.state.desc, origin: [origin[0] ?? 0, origin[1] ?? 0, origin[2] ?? 0] };
+            return;
+        }
+        const decalNode = this.decalNodes.get(nodeId);
+        if (decalNode)
+            this.decalNodes.set(nodeId, { ...decalNode, position: [origin[0] ?? 0, origin[1] ?? 0, origin[2] ?? 0] });
+    }
+    removeInstance(nodeId) {
+        const binding = this.emitters.get(nodeId);
+        if (!binding) {
+            this.beams.delete(nodeId);
+            this.decalNodes.delete(nodeId);
+            const trail = this.trails.get(nodeId);
+            if (trail) {
+                trail.trail.clear();
+                this.ribbons.removeTrail(nodeId);
+                this.trails.delete(nodeId);
+            }
+            this.meshBatches.delete(nodeId);
+            return;
+        }
+        binding.state.live = 0;
+        this.emitters.delete(nodeId);
+        this.diagnostics.untrack(nodeId);
+    }
+    /** Sim advance — runs inside app.onFrame, before the renderer submits. */
+    frame(dt) {
+        if (this.disposed)
+            return;
+        this.time += dt;
+        // Grouped/nested scene changes re-attach on the scene's own version/nodes
+        // turnover — not on every set/onLoad call.
+        const sig = this.sceneSignature();
+        if (sig.nodes !== this.lastSceneNodes || sig.version !== this.lastSceneVersion) {
+            this.rebuildFromScene();
+        }
+        // §6.6 live fog state — advance transitions + refresh runtime-handle
+        // visibility before the compiler/packers read the resolved spec.
+        this.atmosphere.tick(dt);
+        this.atmosphere.updateFogVisibility(this.app);
+        // Close the previous rendered frame's draw accounting first. The visible
+        // set is the scene's effect nodes that aren't hidden — headless apps have
+        // no frustum, so scene-visible == in-frustum here; the contributor's
+        // frustum cull narrows it further inside the renderer.
+        const visible = new Set();
+        this.walkNodes((n, v) => {
+            if (v)
+                visible.add(n.id ?? n.name ?? "");
+        });
+        this.diagnostics.endFrame(visible, !this.renderBridged || this.renderSincePrevFrame);
+        this.renderSincePrevFrame = false;
+        // Fixed-step sim (CpuEmitter §6.3): app.step(t) hands one large dt to
+        // onFrame. Integrating it in a single Euler step launched or dropped every
+        // particle by v·dt metres — the promote fountains landed below the floor or
+        // far above the frame (runs 38196483050 / 38198732843). Substep at ≤1/60 s,
+        // capped at 30 s of simulation per frame like createEmitter's prewarm.
+        const substeps = dt > 0 ? Math.min(Math.ceil(dt * 60 - 1e-6), 1800) : 0;
+        const h = substeps > 0 ? dt / substeps : 0;
+        for (const binding of this.emitters.values()) {
+            for (let s = 0; s < substeps; s++)
+                stepEmitter(binding.state, h);
+            this.diagnostics.track({
+                nodeId: binding.lowered.nodeId,
+                effect: binding.lowered.effect,
+                consumer: binding.lowered.consumer,
+                live: binding.state.live,
+                sim: binding.lowered.sim,
+                softDepth: binding.lowered.batch.softDepth
+            });
+        }
+        // C-27 budget cap: when total live exceeds the tier's particleBudget,
+        // shrink every emitter proportionally and report the refused count as
+        // `budget.culled` (PRD-07 §7.4 "pooled per spec").
+        const live = this.liveCount();
+        if (live > this.budgetCap) {
+            const scale = this.budgetCap / live;
+            let kept = 0;
+            for (const binding of this.emitters.values()) {
+                binding.state.live = Math.floor(binding.state.live * scale);
+                kept += binding.state.live;
+            }
+            this.culledTotal += live - kept;
+        }
+        for (const batch of this.meshBatches.values())
+            batch.step(dt);
+        this.transientLights.step(dt);
+        this.diagnostics.setFrameStats(this.emitters.size, this.liveCount());
+        this.diagnostics.setBudget({ tier: this.tier, cap: this.budgetCap, culled: this.culledTotal });
+    }
+    /**
+     * §8.3 GPU sim requests — read by the prd07.gpuSims contributor, which owns
+     * the RenderDevice and instantiates one ParticleGpuSim per emitter whose
+     * `sim` lowered to "gpu". The CPU emitter keeps running as the draw source
+     * until the batch pass gains the texture-fetch variant (PARTICLE_SOURCE).
+     */
+    gpuSimFeed() {
+        const out = [];
+        for (const binding of this.emitters.values()) {
+            if (binding.lowered.sim !== "gpu")
+                continue;
+            const d = binding.lowered.emitter;
+            out.push({
+                nodeId: d.nodeId,
+                batchKey: d.key,
+                emitCount: d.emissionRate / 60,
+                spec: {
+                    capacity: d.capacity,
+                    lifetimeMax: d.life[1],
+                    gravity: [0, d.gravity, 0],
+                    drag: d.drag,
+                    seed: d.seed,
+                    emitter: { origin: d.origin, direction: d.direction, spread: d.spread, speed: d.speed }
+                }
+            });
+        }
+        return out;
+    }
+    /**
+     * RenderSource feed — invoked by the prd07.particles contributor (collect).
+     * Emitters are coalesced into one batch per §6.2.2 material key (blend,
+     * atlas, stretch, frameBlend, softDepth): two additive emitters on the same
+     * atlas submit a single instanced draw.
+     */
+    feed(hook) {
+        this.frameBatchMembers.clear();
+        const groups = new Map();
+        for (const binding of this.emitters.values()) {
+            const live = writeEmitterInstances(binding.state, binding.scratch);
+            this.frameLive.set(binding.lowered.nodeId, live);
+            const key = binding.lowered.emitter.key;
+            let group = groups.get(key);
+            if (!group)
+                groups.set(key, (group = { first: binding, parts: [] }));
+            group.parts.push({ binding, live });
+        }
+        const seenKeys = new Set();
+        for (const [key, group] of groups) {
+            seenKeys.add(key);
+            const totalLive = group.parts.reduce((s, p) => s + p.live, 0);
+            const flipbook = group.first.lowered.emitter.flipbook;
+            const desc = {
+                key,
+                capacity: group.parts.reduce((s, p) => s + p.binding.lowered.emitter.capacity, 0),
+                source: "cpu",
+                atlas: flipbook ? flipbookTexture(flipbook) : softDotTexture(),
+                ...(flipbook ? { atlasGrid: [flipbook.columns ?? 1, flipbook.rows ?? 1], atlasStraightAlpha: true } : {}),
+                blend: group.first.lowered.batch.blend,
+                shading: group.first.lowered.batch.shading,
+                softDepth: group.first.lowered.batch.softDepth,
+                ...(group.first.lowered.batch.softDistance !== undefined ? { softDistance: group.first.lowered.batch.softDistance } : {}),
+                ...(group.first.lowered.batch.nearFade !== undefined ? { nearFade: group.first.lowered.batch.nearFade } : {}),
+                stretch: group.first.lowered.batch.stretch,
+                frameBlend: group.first.lowered.batch.frameBlend,
+                ...(group.first.lowered.batch.lowRes === true ? { lowRes: true } : {})
+            };
+            this.lastHook = hook;
+            let handle = this.batchHandles.get(key) ?? null;
+            handle = hook.upsertBatch(desc);
+            this.batchHandles.set(key, handle);
+            if (totalLive === 0) {
+                // Keep the batch alive but empty so a revive doesn't thrash capacity.
+                hook.writeInstances(handle, group.first.scratch, 0);
+                continue;
+            }
+            let data;
+            if (group.parts.length === 1) {
+                const part = group.parts[0];
+                data = part.binding.scratch.subarray(0, part.live * 16);
+            }
+            else {
+                data = this.concatScratch(key, totalLive * 16, group.parts);
+            }
+            hook.writeInstances(handle, data, totalLive);
+            this.frameBatchMembers.set(key, group.parts.filter((p) => p.live > 0).map((p) => p.binding.lowered.nodeId));
+        }
+        // Retire batches whose key no emitter fed this frame.
+        for (const [key, handle] of this.batchHandles) {
+            if (!seenKeys.has(key)) {
+                hook.removeBatch(handle);
+                this.batchHandles.delete(key);
+            }
+        }
+    }
+    concatScratch(key, floats, parts) {
+        let buf = this.groupScratch.get(key);
+        if (!buf || buf.length < floats) {
+            buf = new Float32Array(Math.max(64, floats));
+            this.groupScratch.set(key, buf);
+        }
+        let off = 0;
+        for (const part of parts) {
+            if (part.live === 0)
+                continue;
+            buf.set(part.binding.scratch.subarray(0, part.live * 16), off);
+            off += part.live * 16;
+        }
+        return buf.subarray(0, floats);
+    }
+    /** Observed draws — invoked by the contributor after queue collection. */
+    afterDraw(diag) {
+        this.drawFeedQueue = diag;
+        // Attribute the frame's draws per emitter: a merged batch's draw counts
+        // once for every member node (each node's pixels went through that call),
+        // so zero-pixel accounting stays per-node honest.
+        for (const nodeIds of this.frameBatchMembers.values()) {
+            for (const nodeId of nodeIds) {
+                this.diagnostics.trackDraw(nodeId, 1, this.frameLive.get(nodeId) ?? 0);
+            }
+        }
+        for (const error of diag.errors) {
+            this.diagnostics.note(error.code, error.nodeId, error.message);
+        }
+        if (diag.deviceCounters !== undefined) {
+            this.diagnostics.noteDeviceReadbacks(diag.deviceCounters.readbacks);
+        }
+    }
+    culled() {
+        return this.culledTotal;
+    }
+    /** P2-T7 — transient flash for burst presets (impact/explosion/super-flash). */
+    flashLight(flash) {
+        return this.transientLights.flash(flash);
+    }
+    /** CollectedLights published to the RenderSource each frame (C-01 collect). */
+    collectedLights() {
+        return this.transientLights.collect();
+    }
+    liveCount() {
+        let total = 0;
+        for (const binding of this.emitters.values())
+            total += binding.state.live;
+        return total;
+    }
+    emitterIds() {
+        return [...this.emitters.keys()];
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.offFrame();
+        this.emitters.clear();
+    }
+}
+//# sourceMappingURL=ProductionEffectSystem.js.map