@waica/engine 0.23.0 → 0.25.0

package/dist/particle-batch.js

@@ -1,8 +1,9 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 import { reportRejection } from './report-rejection.js';
 import { ParticlePool, particleValueAt, } from './particle-pool.js';
 import { projectIsometric } from './projection.js';
 import { refreshParticleSortBounds } from './particle-sort-bounds.js';
+import { TRANSPARENT_TEXEL_ALPHA } from './render-layers.js';
 function createGeometry(capacity) {
     const geometry = new THREE.BufferGeometry();
     const uvs = new Float32Array(capacity * 8);
@@ -38,8 +39,8 @@ export class ParticleBatch {
         this._layer = Number.isFinite(layer) ? layer : 0;
         this.material = new THREE.MeshBasicMaterial({
             color: 0xffffff,
-            transparent: true,
-            vertexColors: true,
+            // alphaTest: see TRANSPARENT_TEXEL_ALPHA (an Emissive behind shows through transparent texels).
+            transparent: true, alphaTest: TRANSPARENT_TEXEL_ALPHA, vertexColors: true,
             depthTest: true,
             depthWrite: true,
             blending: blend === 'additive' ? THREE.AdditiveBlending : THREE.NormalBlending,
@@ -116,6 +117,9 @@ export class ParticleBatch {
         colors.needsUpdate = true;
         this.sortIndices();
         this.mesh.geometry.setDrawRange(0, this.active * 6);
+        // WebGPURenderer issues a zero-count draw (WebGLRenderer skipped it):
+        // an empty batch is not drawn at all.
+        this.mesh.visible = this.active > 0;
     }
     ySortEntries() {
         this.sortEntrySlots();

package/dist/particle-sort-bounds.d.ts

@@ -1,3 +1,3 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
 export declare function refreshParticleSortBounds(geometry: THREE.BufferGeometry, active: number, emptyZ: number): void;

package/dist/particle-sort-bounds.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import * as THREE from 'three/webgpu';
 /** Keeps Three's transparent-object sort key on live vertices, never unused capacity. */
 export function refreshParticleSortBounds(geometry, active, emptyZ) {
     const positions = geometry.getAttribute('position');

package/dist/pointer.js

@@ -140,7 +140,7 @@ export class Pointer {
                     renderX <= centerX + halfW &&
                     renderY >= centerY - halfH &&
                     renderY <= centerY + halfH) {
-                    // Matches Game.applyYSort's key exactly: the entity's node
+                    // Matches applyYSort (render-sort.ts)'s key exactly: the entity's node
                     // position, which for an isometric scene is the projected Y (the
                     // same `anchor.y` just used to place this box), not the logical one.
                     hits.push({ entity, layer: box.layer, y: anchor.y });

package/dist/post-effects.d.ts

@@ -0,0 +1,33 @@
+import { type ColorGradeEffect, type VignetteEffect } from './scene-render-options.js';
+import type { SceneRenderJson } from './scene.js';
+/**
+ * `game.post` (issue #78): the live scene's Post Effects — a vignette and a
+ * color grade, each off (null) unless its scene declares it or a game turns
+ * it on. With either on, the frame renders through a render target and one
+ * full-screen pass; with both off, it draws straight to the canvas. Camera
+ * Effects (ADR 0020) sit above and are never altered. They die with their scene.
+ */
+export declare class GamePost {
+    private state;
+    /** The vignette now, a copy; null when off. */
+    get vignette(): VignetteEffect | null;
+    /**
+     * Turns the vignette off with null, or changes it field by field over the
+     * current one (absent fields take their defaults when it was off), clamped to 0..1.
+     */
+    set vignette(value: Partial<VignetteEffect> | null);
+    /** The color grade now, a copy; null when off. */
+    get colorGrade(): ColorGradeEffect | null;
+    /**
+     * Turns the color grade off with null, or changes it field by field over the
+     * current one (absent fields neutral when it was off), clamped — like
+     * `game.lighting.ambient`, so a tween of one field keeps the others.
+     */
+    set colorGrade(value: Partial<ColorGradeEffect> | null);
+    /** Whether any Post Effect is on. */
+    get active(): boolean;
+    /** Adopts a scene's `render.post`, replacing whatever the previous scene left. Called by Game. */
+    loadScene(render: SceneRenderJson | undefined): void;
+    /** Every effect off again. */
+    unloadScene(): void;
+}

package/dist/post-effects.js

@@ -0,0 +1,48 @@
+import { resolveColorGrade, resolvePostEffects, resolveVignette, } from './scene-render-options.js';
+/**
+ * `game.post` (issue #78): the live scene's Post Effects — a vignette and a
+ * color grade, each off (null) unless its scene declares it or a game turns
+ * it on. With either on, the frame renders through a render target and one
+ * full-screen pass; with both off, it draws straight to the canvas. Camera
+ * Effects (ADR 0020) sit above and are never altered. They die with their scene.
+ */
+export class GamePost {
+    state = resolvePostEffects(undefined);
+    /** The vignette now, a copy; null when off. */
+    get vignette() {
+        const { vignette } = this.state;
+        return vignette ? { ...vignette } : null;
+    }
+    /**
+     * Turns the vignette off with null, or changes it field by field over the
+     * current one (absent fields take their defaults when it was off), clamped to 0..1.
+     */
+    set vignette(value) {
+        this.state = { ...this.state, vignette: value ? resolveVignette({ ...this.state.vignette, ...value }) : null };
+    }
+    /** The color grade now, a copy; null when off. */
+    get colorGrade() {
+        const { colorGrade } = this.state;
+        return colorGrade ? { ...colorGrade } : null;
+    }
+    /**
+     * Turns the color grade off with null, or changes it field by field over the
+     * current one (absent fields neutral when it was off), clamped — like
+     * `game.lighting.ambient`, so a tween of one field keeps the others.
+     */
+    set colorGrade(value) {
+        this.state = { ...this.state, colorGrade: value ? resolveColorGrade({ ...this.state.colorGrade, ...value }) : null };
+    }
+    /** Whether any Post Effect is on. */
+    get active() {
+        return this.state.vignette !== null || this.state.colorGrade !== null;
+    }
+    /** Adopts a scene's `render.post`, replacing whatever the previous scene left. Called by Game. */
+    loadScene(render) {
+        this.state = resolvePostEffects(render?.post);
+    }
+    /** Every effect off again. */
+    unloadScene() {
+        this.loadScene(undefined);
+    }
+}

package/dist/post-pass.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from 'three/webgpu';
+import type { PostEffectsState } from './scene-render-options.js';
+/**
+ * The Post Effects' render target and pass: the frame is drawn into `target`
+ * exactly as onto the canvas — 8-bit, sRGB-encoded, blending on sRGB values
+ * (ADR 0025's canvas path) — at the light-map resolution with nearest upscale
+ * (E2), then `draw` writes it to the canvas through the effects. A half-float
+ * linear target drew nothing on CI's headless Linux WebGPU (PR #150), and it
+ * changed every translucent edge.
+ */
+export declare class PostPass {
+    readonly target: THREE.RenderTarget<THREE.Texture<unknown, THREE.TextureEventMap>, THREE.RenderTargetEventMap>;
+    private readonly uniforms;
+    private readonly drawnLikeCanvas;
+    private readonly quad;
+    /** Sizes the target for this frame. */
+    resize(width: number, height: number): void;
+    /** Draws the target to whatever is bound now (the canvas), with this frame's effects. */
+    draw(renderer: THREE.WebGPURenderer, effects: PostEffectsState): void;
+    private setVignette;
+    private setColorGrade;
+    dispose(): void;
+}

package/dist/post-pass.js

@@ -0,0 +1,93 @@
+import { clamp, dot, float, length, max, mix, texture, uniform, uv, vec3, vec4 } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+import { FrameQuad } from './frame-quad.js';
+import { hexChannels } from './scene-lighting.js';
+import { drawLikeCanvas } from './render-output.js';
+function createUniforms() {
+    return {
+        vignetteOn: uniform(0),
+        vignetteIntensity: uniform(0),
+        vignetteRadius: uniform(0),
+        gradeOn: uniform(0),
+        tint: uniform(new THREE.Vector3(1, 1, 1)),
+        contrast: uniform(1),
+        saturation: uniform(1),
+    };
+}
+/**
+ * The single full-screen pass of the Post Effects (issue #78 CA-11): it reads
+ * the frame from the target, already in the canvas's sRGB values, grades it —
+ * tint, then saturation around Rec. 709 luma, then contrast around mid grey —
+ * and darkens it towards the corners. Its output is the canvas's sRGB value.
+ */
+function createPostMaterial(scene, u) {
+    const material = new THREE.MeshBasicNodeMaterial();
+    // Already the canvas's sRGB values (drawLikeCanvas): graded as they would show.
+    const display = texture(scene, uv()).rgb;
+    const tinted = display.mul(u.tint);
+    const luma = dot(tinted, vec3(0.2126, 0.7152, 0.0722));
+    const saturated = mix(vec3(luma, luma, luma), tinted, u.saturation);
+    const graded = saturated.sub(0.5).mul(u.contrast).add(0.5);
+    const color = mix(display, graded, u.gradeOn);
+    // 0 at the centre, 1 at the corners.
+    const distance = length(uv().sub(0.5).mul(2)).div(Math.SQRT2);
+    const ramp = clamp(distance.sub(u.vignetteRadius).div(max(float(1).sub(u.vignetteRadius), 1e-3)), 0, 1);
+    const eased = ramp.mul(ramp).mul(float(3).sub(ramp.mul(2)));
+    const vignette = float(1).sub(u.vignetteIntensity.mul(eased).mul(u.vignetteOn));
+    material.fragmentNode = vec4(clamp(color.mul(vignette), vec3(0, 0, 0), vec3(1, 1, 1)), 1);
+    material.depthTest = false;
+    material.depthWrite = false;
+    return material;
+}
+/**
+ * The Post Effects' render target and pass: the frame is drawn into `target`
+ * exactly as onto the canvas — 8-bit, sRGB-encoded, blending on sRGB values
+ * (ADR 0025's canvas path) — at the light-map resolution with nearest upscale
+ * (E2), then `draw` writes it to the canvas through the effects. A half-float
+ * linear target drew nothing on CI's headless Linux WebGPU (PR #150), and it
+ * changed every translucent edge.
+ */
+export class PostPass {
+    target = new THREE.RenderTarget(1, 1, {
+        type: THREE.UnsignedByteType,
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+        depthBuffer: true,
+        // The canvas's own MSAA (antialias: true): geometry edges match the frame without post.
+        samples: 4,
+    });
+    uniforms = createUniforms();
+    drawnLikeCanvas = drawLikeCanvas(this.target);
+    quad = new FrameQuad(createPostMaterial(this.target.texture, this.uniforms));
+    /** Sizes the target for this frame. */
+    resize(width, height) {
+        if (this.target.width !== width || this.target.height !== height)
+            this.target.setSize(width, height);
+    }
+    /** Draws the target to whatever is bound now (the canvas), with this frame's effects. */
+    draw(renderer, effects) {
+        this.setVignette(effects.vignette);
+        this.setColorGrade(effects.colorGrade);
+        this.quad.render(renderer);
+    }
+    setVignette(vignette) {
+        const u = this.uniforms;
+        u.vignetteOn.value = vignette ? 1 : 0;
+        u.vignetteIntensity.value = vignette ? vignette.intensity : 0;
+        u.vignetteRadius.value = vignette ? vignette.radius : 0;
+    }
+    setColorGrade(grade) {
+        const u = this.uniforms;
+        const neutral = { tint: '#ffffff', contrast: 1, saturation: 1 };
+        const { tint, contrast, saturation } = grade ?? neutral;
+        u.gradeOn.value = grade ? 1 : 0;
+        const [r, g, b] = hexChannels(tint);
+        u.tint.value.set(r, g, b);
+        u.contrast.value = contrast;
+        u.saturation.value = saturation;
+    }
+    dispose() {
+        this.target.dispose();
+        this.quad.dispose();
+    }
+}

package/dist/render-layers.d.ts

@@ -0,0 +1,18 @@
+import type * as THREE from 'three/webgpu';
+/**
+ * The three.js layer an Emissive drawable lives on, alone (issue #78 CA-10).
+ * The Game's camera sees layer 0 and this one, so an unlit scene draws an
+ * Emissive drawable in place like any other; a lit scene draws layer 0, then
+ * its light-map, then this layer at full brightness (ADR 0026).
+ */
+export declare const EMISSIVE_LAYER = 1;
+/** Puts `object` on the Emissive layer alone, or back on the default layer 0. */
+export declare function setEmissive(object: THREE.Object3D, emissive: boolean): void;
+/**
+ * The alphaTest every drawable carries (PR #150 review): a texel whose alpha
+ * byte is 0 is discarded instead of drawn. It contributes no color either way
+ * (normal blending keeps the frame), but discarded it also writes no depth, so
+ * an Emissive drawable drawn after the lit pass shows through the transparent
+ * texels of a lit sprite in front of it, and stays hidden behind its opaque ones.
+ */
+export declare const TRANSPARENT_TEXEL_ALPHA: number;

package/dist/render-layers.js

@@ -0,0 +1,19 @@
+/**
+ * The three.js layer an Emissive drawable lives on, alone (issue #78 CA-10).
+ * The Game's camera sees layer 0 and this one, so an unlit scene draws an
+ * Emissive drawable in place like any other; a lit scene draws layer 0, then
+ * its light-map, then this layer at full brightness (ADR 0026).
+ */
+export const EMISSIVE_LAYER = 1;
+/** Puts `object` on the Emissive layer alone, or back on the default layer 0. */
+export function setEmissive(object, emissive) {
+    object.layers.set(emissive ? EMISSIVE_LAYER : 0);
+}
+/**
+ * The alphaTest every drawable carries (PR #150 review): a texel whose alpha
+ * byte is 0 is discarded instead of drawn. It contributes no color either way
+ * (normal blending keeps the frame), but discarded it also writes no depth, so
+ * an Emissive drawable drawn after the lit pass shows through the transparent
+ * texels of a lit sprite in front of it, and stays hidden behind its opaque ones.
+ */
+export const TRANSPARENT_TEXEL_ALPHA = 1 / 512;

package/dist/render-output.d.ts

@@ -0,0 +1,34 @@
+import * as THREE from 'three/webgpu';
+/**
+ * Makes WebGPURenderer draw the way WebGLRenderer did (ADR 0025): straight
+ * into the 8-bit canvas, each material encoding its color to sRGB in its own
+ * shader, so alpha blending happens on sRGB values. By default three renders
+ * into a linear half-float target and converts it in an extra full-screen
+ * pass: blending in linear space, which changes every translucent edge, and
+ * one more draw per frame. A render target keeps the linear working space.
+ */
+export declare function drawStraightToCanvas(renderer: THREE.WebGPURenderer): void;
+/**
+ * Makes `target` receive what the canvas would (issue #78): every material
+ * encodes to sRGB into it and blends on sRGB values, so a frame drawn there
+ * and copied to the canvas is the frame drawn straight to the canvas. The
+ * Post Effects' 8-bit target.
+ */
+export declare function drawLikeCanvas(target: THREE.RenderTarget): THREE.RenderTarget;
+/**
+ * The scene background for a canvas drawn straight: three clears with a
+ * color's working-space (linear) components, and the canvas stores sRGB, so
+ * the clear carries the color's sRGB components — what WebGLRenderer wrote.
+ */
+export declare function canvasBackground(color: THREE.ColorRepresentation): THREE.Color;
+/**
+ * Applies a material map's UV transform (offset, repeat) per vertex, as
+ * WebGLRenderer's `vMapUv` did, instead of per fragment as three's node
+ * materials do by default. At a quad's corners the UV is 0 or 1, so the
+ * transformed corner UV is the same float however a shader compiler fuses
+ * the multiply and add — per fragment it is not, and a sprite whose sheet
+ * offset is not 0 could then sample a texel row apart in two shaders of the
+ * same picture (a Sprite Batch and its per-sprite fallback, ADR 0024).
+ * Textures with their own UV node, or sampled outside a mesh, stay three's.
+ */
+export declare function mapUvPerVertex(renderer: THREE.WebGPURenderer): void;

package/dist/render-output.js

@@ -0,0 +1,60 @@
+import { uv, vertexStage, workingToColorSpace } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+/**
+ * Makes WebGPURenderer draw the way WebGLRenderer did (ADR 0025): straight
+ * into the 8-bit canvas, each material encoding its color to sRGB in its own
+ * shader, so alpha blending happens on sRGB values. By default three renders
+ * into a linear half-float target and converts it in an extra full-screen
+ * pass: blending in linear space, which changes every translucent edge, and
+ * one more draw per frame. A render target keeps the linear working space.
+ */
+export function drawStraightToCanvas(renderer) {
+    // The working space as output: three then needs no intermediate target.
+    renderer.outputColorSpace = THREE.ColorManagement.workingColorSpace;
+    const context = renderer.contextNode.value;
+    context.getOutput = (output, builder) => {
+        const target = builder.renderer.getRenderTarget();
+        const likeCanvas = target === null || (typeof target === 'object' && canvasLike.has(target));
+        return likeCanvas ? workingToColorSpace(output, THREE.SRGBColorSpace) : output;
+    };
+}
+/** Render targets that hold a frame exactly as the canvas would: sRGB-encoded 8-bit values. */
+const canvasLike = new WeakSet();
+/**
+ * Makes `target` receive what the canvas would (issue #78): every material
+ * encodes to sRGB into it and blends on sRGB values, so a frame drawn there
+ * and copied to the canvas is the frame drawn straight to the canvas. The
+ * Post Effects' 8-bit target.
+ */
+export function drawLikeCanvas(target) {
+    canvasLike.add(target);
+    return target;
+}
+/**
+ * The scene background for a canvas drawn straight: three clears with a
+ * color's working-space (linear) components, and the canvas stores sRGB, so
+ * the clear carries the color's sRGB components — what WebGLRenderer wrote.
+ */
+export function canvasBackground(color) {
+    const { r, g, b } = new THREE.Color(color).getRGB({ r: 0, g: 0, b: 0 }, THREE.SRGBColorSpace);
+    return new THREE.Color().setRGB(r, g, b, THREE.LinearSRGBColorSpace);
+}
+/**
+ * Applies a material map's UV transform (offset, repeat) per vertex, as
+ * WebGLRenderer's `vMapUv` did, instead of per fragment as three's node
+ * materials do by default. At a quad's corners the UV is 0 or 1, so the
+ * transformed corner UV is the same float however a shader compiler fuses
+ * the multiply and add — per fragment it is not, and a sprite whose sheet
+ * offset is not 0 could then sample a texel row apart in two shaders of the
+ * same picture (a Sprite Batch and its per-sprite fallback, ADR 0024).
+ * Textures with their own UV node, or sampled outside a mesh, stay three's.
+ */
+export function mapUvPerVertex(renderer) {
+    const context = renderer.contextNode.value;
+    context.getUV = (texture, builder) => {
+        if (texture.uvNode !== null || !builder.object.isMesh)
+            return null;
+        texture.setUpdateMatrix(false);
+        return vertexStage(texture.getTransformedUV(uv(texture.value.channel)));
+    };
+}

package/dist/render-readiness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The GPU API a Game draws through (CONTEXT.md): `webgpu` when the browser
+ * offers it, otherwise three's own WebGL2 fallback. The browser decides; no
+ * option forces either one (ADR 0025).
+ */
+export type RenderBackend = 'webgpu' | 'webgl2';
+/** The part of three's WebGPURenderer readiness depends on. */
+export interface InitializingRenderer {
+    init(): Promise<unknown>;
+    dispose(): Promise<void>;
+    /** After init(), the backend it settled on: the WebGPU one, or the WebGL2 fallback. */
+    readonly backend: object;
+}
+/**
+ * A renderer's asynchronous initialization, owned by its Game: started at
+ * construction, settled once, and the only gate between a frame and a draw.
+ * `promise` is what `game.ready()` hands out; a failure rejects it with an
+ * error naming both Render Backends and is also reported to `onFailure`.
+ */
+export declare class RenderReadiness {
+    private readonly renderer;
+    readonly promise: Promise<void>;
+    private state;
+    constructor(renderer: InitializingRenderer, onFailure: (error: Error) => void);
+    /** Runs `then` once the renderer is ready; never after a failed init. */
+    whenReady(then: () => void): void;
+    /** True once the renderer can draw. */
+    get isReady(): boolean;
+    /** The Render Backend after a successful init; null before it and after a failure. */
+    get backend(): RenderBackend | null;
+    /**
+     * Frees the renderer: right away once it is ready, after init settles
+     * while it is pending (three cannot dispose a renderer mid-init), never
+     * after a failed init (nothing was allocated).
+     */
+    disposeRenderer(): void;
+}

package/dist/render-readiness.js

@@ -0,0 +1,61 @@
+/** three flags its WebGPU backend with `isWebGPUBackend`; its WebGL2 fallback has no such flag. */
+function backendOf(backend) {
+    return 'isWebGPUBackend' in backend && backend.isWebGPUBackend === true ? 'webgpu' : 'webgl2';
+}
+function describeCause(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * A renderer's asynchronous initialization, owned by its Game: started at
+ * construction, settled once, and the only gate between a frame and a draw.
+ * `promise` is what `game.ready()` hands out; a failure rejects it with an
+ * error naming both Render Backends and is also reported to `onFailure`.
+ */
+export class RenderReadiness {
+    renderer;
+    promise;
+    state = { status: 'pending' };
+    constructor(renderer, onFailure) {
+        this.renderer = renderer;
+        this.promise = renderer.init().then(() => {
+            this.state = { status: 'ready', backend: backendOf(renderer.backend) };
+        }, (cause) => {
+            this.state = { status: 'failed' };
+            const error = new Error(`No Render Backend could initialize: neither webgpu nor webgl2 is available (${describeCause(cause)}).`, { cause });
+            onFailure(error);
+            throw error;
+        });
+        // The rejection belongs to whoever awaits game.ready(); a Game nobody
+        // asked must not surface it as an unhandled rejection on top of that.
+        this.promise.catch(() => { });
+    }
+    /** Runs `then` once the renderer is ready; never after a failed init. */
+    whenReady(then) {
+        this.promise.then(then, () => { });
+    }
+    /** True once the renderer can draw. */
+    get isReady() {
+        return this.state.status === 'ready';
+    }
+    /** The Render Backend after a successful init; null before it and after a failure. */
+    get backend() {
+        return this.state.status === 'ready' ? this.state.backend : null;
+    }
+    /**
+     * Frees the renderer: right away once it is ready, after init settles
+     * while it is pending (three cannot dispose a renderer mid-init), never
+     * after a failed init (nothing was allocated).
+     */
+    disposeRenderer() {
+        const dispose = () => {
+            this.renderer.dispose().catch((error) => {
+                console.error('[waica] could not dispose the renderer', error);
+            });
+        };
+        if (this.isReady) {
+            dispose();
+            return;
+        }
+        this.promise.then(dispose, () => { });
+    }
+}

package/dist/render-sort.d.ts

@@ -35,3 +35,17 @@ export declare function isYSortBatchParticipant(value: unknown): value is YSortB
  * apart, so their band is exactly the old fixed 0.01.
  */
 export declare function ySortZ(entries: readonly YSortEntry[]): number[];
+/** What applyYSort reads of an entity: its components and the Y its node draws at. */
+export interface YSortEntity {
+    readonly components: readonly unknown[];
+    readonly node: {
+        readonly position: {
+            readonly y: number;
+        };
+    };
+}
+/**
+ * Under y-sort, re-derives every participant's z from layer band + entity Y:
+ * the scene's entities, then the batch participants its drains hold.
+ */
+export declare function applyYSort(entities: readonly YSortEntity[], drains: readonly YSortBatchParticipant[]): void;

package/dist/render-sort.js

@@ -48,3 +48,40 @@ export function ySortZ(entries) {
     }
     return z;
 }
+/**
+ * Under y-sort, re-derives every participant's z from layer band + entity Y:
+ * the scene's entities, then the batch participants its drains hold.
+ */
+export function applyYSort(entities, drains) {
+    const singles = [];
+    const batches = [];
+    const entries = [];
+    for (const entity of entities) {
+        for (const component of entity.components) {
+            if (isYSortBatchParticipant(component)) {
+                const batchEntries = component.ySortEntries();
+                batches.push({ participant: component, start: entries.length, count: batchEntries.length });
+                entries.push(...batchEntries);
+            }
+            else if (isYSortParticipant(component)) {
+                singles.push({ participant: component, index: entries.length });
+                entries.push({ layer: component.layer, y: entity.node.position.y });
+            }
+        }
+    }
+    for (const participant of drains) {
+        const batchEntries = participant.ySortEntries();
+        batches.push({ participant, start: entries.length, count: batchEntries.length });
+        entries.push(...batchEntries);
+    }
+    const z = ySortZ(entries);
+    for (const { participant, index } of singles) {
+        const sortZ = z[index];
+        if (sortZ === undefined)
+            throw new Error(`ySortZ returned no z for y-sort participant ${index}`);
+        participant.setSortZ(sortZ);
+    }
+    for (const { participant, start, count } of batches) {
+        participant.setSortZs(z.slice(start, start + count));
+    }
+}

package/dist/runtime-bridge.d.ts

@@ -1,4 +1,5 @@
 import type { AssetStatus } from './assets/asset-loader.js';
+import type { RenderBackend } from './render-readiness.js';
 import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
@@ -20,9 +21,13 @@ export type RuntimeMode = 'paused' | 'real-time';
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
  * optional `value` in (0, 1] and that every control result carries
- * `actionValues` beside `heldActions`.
+ * `actionValues` beside `heldActions`. `render-backend` (issue #140, ADR
+ * 0025) announces that every metadata carries `backend`: the Render Backend
+ * once the renderer is ready, null before — a Run Session waits for it — and
+ * that a renderer that fails to initialize reports through the activation's
+ * `fail`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions', 'render-backend'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -32,6 +37,8 @@ export interface RuntimeMetadata {
     capabilities: readonly string[];
     /** `game.assets.status` at the moment of the read — reading it never advances `frame`. */
     assets: AssetStatus;
+    /** The Render Backend once `game.ready()` resolved; null until then (and for good after a failed init). */
+    backend: RenderBackend | null;
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'release';
@@ -76,11 +83,18 @@ export interface RuntimeBridge {
     inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     control(request: RuntimeControlRequest): RuntimeControlResult;
 }
+/** Why a Game can never become operational; reported through the activation. */
+export interface RuntimeBridgeFailure {
+    code: 'render-backend-failed';
+    message: string;
+}
 /** Ephemeral pre-page hook installed by the owner of a browser context. */
 export interface RuntimeBridgeActivation {
     readonly protocolVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     register(bridge: RuntimeBridge): void;
     unregister(bridge: RuntimeBridge): void;
+    /** Optional: told when the Game's renderer fails to initialize, so the owner stops waiting. */
+    fail?(failure: RuntimeBridgeFailure): void;
 }
 export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
 export interface RuntimeBridgeHost {
@@ -104,6 +118,8 @@ export interface RuntimeBridgeHost {
     availableScenes(): string[];
     /** A fresh `game.assets.status`. */
     assets(): AssetStatus;
+    /** The Render Backend, null until the renderer is ready. */
+    backend(): RenderBackend | null;
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -20,7 +20,11 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
  * optional `value` in (0, 1] and that every control result carries
- * `actionValues` beside `heldActions`.
+ * `actionValues` beside `heldActions`. `render-backend` (issue #140, ADR
+ * 0025) announces that every metadata carries `backend`: the Render Backend
+ * once the renderer is ready, null before — a Run Session waits for it — and
+ * that a renderer that fails to initialize reports through the activation's
+ * `fail`.
  */
 export const RUNTIME_BRIDGE_CAPABILITIES = [
     'click',
@@ -29,6 +33,7 @@ export const RUNTIME_BRIDGE_CAPABILITIES = [
     'assets',
     'camera-effects',
     'analog-actions',
+    'render-backend',
 ];
 export class RuntimeBridgeOperationError extends Error {
     code;
@@ -79,6 +84,7 @@ export class EngineRuntimeBridge {
             simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
             assets: this.host.assets(),
+            backend: this.host.backend(),
         };
     }
     inspect(filters = {}) {

package/dist/runtime-inspection.d.ts

@@ -3,6 +3,7 @@ import type { CameraEffectsState } from './camera-effects.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
+import { type RuntimeSnapshotLighting, type RuntimeSnapshotPost } from './runtime-lighting-snapshot.js';
 export type ProjectionMarkerKind = 'cycle' | 'unsupported' | 'error' | 'truncated';
 export interface ProjectionMarker {
     $waica: ProjectionMarkerKind | 'date' | 'bigint' | 'map' | 'set';
@@ -124,6 +125,10 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     time: RuntimeSnapshotTime;
     ui: RuntimeSnapshotUi;
     camera: RuntimeSnapshotCamera;
+    /** Ambient Light and live Lights (issue #78 CA-12), logical coordinates; never filtered. */
+    lighting: RuntimeSnapshotLighting;
+    /** Post Effects (issue #78 CA-12), each null when off; never filtered. */
+    post: RuntimeSnapshotPost;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;