@driftengine/core 3.61.0

package/dist/render/pointShadowBudget.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Which point-shadow maps get to bake this frame, and in what order.
+ *
+ * Baking is six full passes over the static world per light, and the renderer used to
+ * do every stale one in the frame it noticed. That is fine in the steady state, where
+ * nothing is stale, and catastrophic on the frame it stops being true: walking into a
+ * courtyard makes eight lights stale at once, which is 48 passes in one frame. Measured on
+ * a fast machine at boot, that was two consecutive frames of 89 ms and 99 ms against an
+ * 8.3 ms budget — the hitch about a second after a page load, and a smaller one each
+ * time a new cluster of lamps comes into range.
+ *
+ * Spreading the same work over more frames costs nothing anybody can see. Eight lights
+ * at two faces a frame is 24 frames, a fifth of a second at 120 Hz, during which
+ * shadows resolve progressively instead of the whole game stopping.
+ *
+ * This module only decides the *order*. The renderer spends a face budget walking it,
+ * because lights need different numbers of faces depending on how far through a bake
+ * they already are.
+ */
+/**
+ * Order the stale maps so the ones with nothing to show go first.
+ *
+ * A light whose map has never been baked contributes no shadow at all until it has one
+ * (see `PointShadowSystem.bind`), so every frame it waits is a frame with a visibly
+ * unlit lamp. A light that has merely drifted past the rebake tolerance is still
+ * sampling a perfectly reasonable map from a few centimetres away, and can wait.
+ * Serving the second kind first would hold a missing shadow hostage to a nearly
+ * invisible correction.
+ *
+ * Within each group the caller's order is preserved, which is the shading pass's own
+ * light order and therefore already sorted by how much each light matters.
+ *
+ * Writes into `out` and returns how many entries it wrote; allocation-free because this
+ * runs every frame.
+ */
+export declare function planPointShadowBakes(
+/** 1 where the map at that slot needs baking. */
+stale: Uint8Array, 
+/** 1 where the map at that slot already holds a usable image. */
+ready: Uint8Array, count: number, out: Int32Array, 
+/**
+ * 1 where this slot's map has gone stale on every recent frame.
+ *
+ * Optional: a caller that omits it gets the two-group order this had before.
+ */
+chronic?: Uint8Array): number;
+/**
+ * The shaded lights that also cast, in the order they were shaded.
+ *
+ * `castsShadow: false` says a light is not worth a cubemap. `selectPointLights` honours
+ * that when it builds the *eligible* list, and that was taken for the whole promise — but
+ * the shaded set is a different list, a caller hands it to `updatePointShadows` as the set
+ * to bind, and a light in it was given a pool slot and baked whatever it had declared. So
+ * the flag held for a lamp out of range and quietly failed for the one in front of you,
+ * which is the only one whose bake is visible.
+ *
+ * It showed up as a shadow with nothing to throw it — a lamp that rides the camera
+ * declines to cast for exactly that reason, and cast anyway.
+ *
+ * Writes into `out` and returns how many it wrote; allocation-free, because this runs
+ * every frame.
+ */
+export declare function selectCastingLights(lights: readonly {
+    castsShadow?: boolean;
+}[], activeWorldIndices: Int32Array, activeCount: number, out: Int32Array): number;
+/** The per-slot scratch a bake round needs. Caller-owned; this runs every frame. */
+export interface BakeScratch {
+    readonly stale: Uint8Array;
+    readonly ready: Uint8Array;
+    readonly order: Int32Array;
+    readonly chronic: Uint8Array;
+    readonly staleRun: Uint8Array;
+    readonly staleOwner: Int32Array;
+}
+export declare function createBakeScratch(pool: number): BakeScratch;
+/** What a pool must expose for a bake round to be planned over it. */
+export interface BakeablePool<M> {
+    readonly pooledCount: number;
+    readonly sampledCount: number;
+    readonly liveMapCount: number;
+    pooledLight(slot: number): number;
+    mapForLight(lightIndex: number): M | undefined;
+    liveOwner(slot: number): number;
+    liveMap(slot: number): M | undefined;
+}
+/** The one thing a bake round cannot do itself: put six faces of a world into a cubemap. */
+export type BakeFaces<M, L> = (map: M, light: L, casters: unknown, maxFaces: number) => number;
+/** What a map must answer for staleness to be decided. */
+export interface StaleCheck {
+    hasBaked: boolean;
+    matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius: number, tolerance: number): boolean;
+}
+/** The light fields a bake round reads. */
+export interface BakeableLight {
+    x: number;
+    y: number;
+    z: number;
+    radius: number;
+    shadowNear: number;
+    sourceRadius: number;
+}
+/**
+ * Spend a frame's face budget across the pool, then refresh the live maps.
+ *
+ * **Every rule in here was bought with a measured frame and none of it is about a device.**
+ * Bakes are spread rather than done the instant they are noticed, because walking into a courtyard
+ * makes eight lights go stale at once — 48 passes over the static world in one frame, measured
+ * at 89 ms and 99 ms in two consecutive frames against an 8.3 ms budget. A slot that has never
+ * baked and is being *sampled* jumps the queue with the whole six, because a light with no
+ * image contributes nothing and a partial cubemap is worse than none; one such jump a frame, so
+ * a cluster coming into range cannot spend the whole budget at once. A slot that is stale every
+ * frame is demoted after three, because a wandering flame would otherwise starve the queue.
+ *
+ * A second implementation of any of that is a backend whose shadows arrive at different moments
+ * — which is not something a parity capture would attribute, because both frames look plausible.
+ * Hence one function, and `bake` as the only thing either backend supplies.
+ */
+export declare function runPointShadowBakes<M extends StaleCheck, L extends BakeableLight>(pool: BakeablePool<M>, lights: readonly L[], facesPerFrame: number, liveFacesPerFrame: number, rebakeDistance: number, faceCount: number, scratch: BakeScratch, staticCasters: unknown, dynamicCasters: unknown, bake: BakeFaces<M, L>): void;

package/dist/render/pointShadowBudget.js

@@ -0,0 +1,221 @@
+/**
+ * Which point-shadow maps get to bake this frame, and in what order.
+ *
+ * Baking is six full passes over the static world per light, and the renderer used to
+ * do every stale one in the frame it noticed. That is fine in the steady state, where
+ * nothing is stale, and catastrophic on the frame it stops being true: walking into a
+ * courtyard makes eight lights stale at once, which is 48 passes in one frame. Measured on
+ * a fast machine at boot, that was two consecutive frames of 89 ms and 99 ms against an
+ * 8.3 ms budget — the hitch about a second after a page load, and a smaller one each
+ * time a new cluster of lamps comes into range.
+ *
+ * Spreading the same work over more frames costs nothing anybody can see. Eight lights
+ * at two faces a frame is 24 frames, a fifth of a second at 120 Hz, during which
+ * shadows resolve progressively instead of the whole game stopping.
+ *
+ * This module only decides the *order*. The renderer spends a face budget walking it,
+ * because lights need different numbers of faces depending on how far through a bake
+ * they already are.
+ */
+/**
+ * Order the stale maps so the ones with nothing to show go first.
+ *
+ * A light whose map has never been baked contributes no shadow at all until it has one
+ * (see `PointShadowSystem.bind`), so every frame it waits is a frame with a visibly
+ * unlit lamp. A light that has merely drifted past the rebake tolerance is still
+ * sampling a perfectly reasonable map from a few centimetres away, and can wait.
+ * Serving the second kind first would hold a missing shadow hostage to a nearly
+ * invisible correction.
+ *
+ * Within each group the caller's order is preserved, which is the shading pass's own
+ * light order and therefore already sorted by how much each light matters.
+ *
+ * Writes into `out` and returns how many entries it wrote; allocation-free because this
+ * runs every frame.
+ */
+export function planPointShadowBakes(
+/** 1 where the map at that slot needs baking. */
+stale, 
+/** 1 where the map at that slot already holds a usable image. */
+ready, count, out, 
+/**
+ * 1 where this slot's map has gone stale on every recent frame.
+ *
+ * Optional: a caller that omits it gets the two-group order this had before.
+ */
+chronic) {
+    let written = 0;
+    // Never baked: nothing to sample until this lands.
+    for (let slot = 0; slot < count && written < out.length; slot++) {
+        if (stale[slot] === 1 && ready[slot] !== 1)
+            out[written++] = slot;
+    }
+    // Baked but drifted: correcting an image that is already close to right.
+    for (let slot = 0; slot < count && written < out.length; slot++) {
+        if (stale[slot] === 1 && ready[slot] === 1 && chronic?.[slot] !== 1)
+            out[written++] = slot;
+    }
+    /*
+     * Last: the maps that will be stale again next frame whatever is done for them.
+     *
+     * A light that moves, or breathes its radius, invalidates its own map every frame — so
+     * a bake buys it one frame and is owed again immediately. Ordered by the caller's
+     * importance alone, which is all the drifted group above uses, such a light sits
+     * permanently ahead of a static one that drifted once and would then stay correct for
+     * an hour; it takes the spread budget forever and the static one never gets its
+     * correction. Importance is the right tie-break between two maps that will *keep* what
+     * they are given, and the wrong one when only one of them will.
+     *
+     * They are still served, and served in full when budget is left over, so a light that
+     * settles catches up on the next frame. They simply cannot hold a settling light
+     * hostage any more.
+     *
+     * This is the scheduling half of the problem only. Whether a light is *worth* a cubemap
+     * at all — a floor-level marker, a lamp riding a camera, a creature standing inside
+     * its own glow — is a question about the content, and `castsShadow` is where a consumer
+     * answers it. No ordering can.
+     */
+    if (chronic !== undefined) {
+        for (let slot = 0; slot < count && written < out.length; slot++) {
+            if (stale[slot] === 1 && ready[slot] === 1 && chronic[slot] === 1)
+                out[written++] = slot;
+        }
+    }
+    return written;
+}
+/**
+ * The shaded lights that also cast, in the order they were shaded.
+ *
+ * `castsShadow: false` says a light is not worth a cubemap. `selectPointLights` honours
+ * that when it builds the *eligible* list, and that was taken for the whole promise — but
+ * the shaded set is a different list, a caller hands it to `updatePointShadows` as the set
+ * to bind, and a light in it was given a pool slot and baked whatever it had declared. So
+ * the flag held for a lamp out of range and quietly failed for the one in front of you,
+ * which is the only one whose bake is visible.
+ *
+ * It showed up as a shadow with nothing to throw it — a lamp that rides the camera
+ * declines to cast for exactly that reason, and cast anyway.
+ *
+ * Writes into `out` and returns how many it wrote; allocation-free, because this runs
+ * every frame.
+ */
+export function selectCastingLights(lights, activeWorldIndices, activeCount, out) {
+    let written = 0;
+    for (let i = 0; i < activeCount && written < out.length; i++) {
+        const worldIndex = activeWorldIndices[i] ?? -1;
+        if (worldIndex < 0)
+            continue;
+        if (lights[worldIndex]?.castsShadow === false)
+            continue;
+        out[written++] = worldIndex;
+    }
+    return written;
+}
+/**
+ * How many consecutive frames a slot must be stale before it is treated as chronically so.
+ *
+ * A light that drifts past the rebake tolerance every frame — a wandering flame — would
+ * otherwise take a bake every frame and starve everything else. Three frames is long enough
+ * that a genuine move still rebakes promptly and short enough that a chronic one is demoted
+ * before it has cost much.
+ */
+const CHRONIC_STALE_FRAMES = 3;
+export function createBakeScratch(pool) {
+    return {
+        stale: new Uint8Array(pool),
+        ready: new Uint8Array(pool),
+        order: new Int32Array(pool),
+        chronic: new Uint8Array(pool),
+        staleRun: new Uint8Array(pool),
+        staleOwner: new Int32Array(pool).fill(-1),
+    };
+}
+/**
+ * Spend a frame's face budget across the pool, then refresh the live maps.
+ *
+ * **Every rule in here was bought with a measured frame and none of it is about a device.**
+ * Bakes are spread rather than done the instant they are noticed, because walking into a courtyard
+ * makes eight lights go stale at once — 48 passes over the static world in one frame, measured
+ * at 89 ms and 99 ms in two consecutive frames against an 8.3 ms budget. A slot that has never
+ * baked and is being *sampled* jumps the queue with the whole six, because a light with no
+ * image contributes nothing and a partial cubemap is worse than none; one such jump a frame, so
+ * a cluster coming into range cannot spend the whole budget at once. A slot that is stale every
+ * frame is demoted after three, because a wandering flame would otherwise starve the queue.
+ *
+ * A second implementation of any of that is a backend whose shadows arrive at different moments
+ * — which is not something a parity capture would attribute, because both frames look plausible.
+ * Hence one function, and `bake` as the only thing either backend supplies.
+ */
+export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFrame, rebakeDistance, faceCount, scratch, staticCasters, dynamicCasters, bake) {
+    /*
+     * Across everything holding a slot, not only what is being shaded. A warm light baked now is
+     * a light that joins the sampled set without a six-face bill — which is the on/off a lamp
+     * used to make as it came into range.
+     */
+    const count = Math.min(pool.pooledCount, scratch.stale.length);
+    for (let slot = 0; slot < count; slot++) {
+        const lightIndex = pool.pooledLight(slot);
+        const light = lightIndex >= 0 ? lights[lightIndex] : undefined;
+        const map = lightIndex >= 0 ? pool.mapForLight(lightIndex) : undefined;
+        const stale = light !== undefined &&
+            map !== undefined &&
+            !map.matchesSource(light.x, light.y, light.z, light.radius, light.shadowNear, light.sourceRadius, rebakeDistance);
+        scratch.stale[slot] = stale ? 1 : 0;
+        scratch.ready[slot] = map !== undefined && map.hasBaked ? 1 : 0;
+        /* The run is per borrower: a slot changing hands starts its patience over. */
+        if (scratch.staleOwner[slot] !== lightIndex) {
+            scratch.staleOwner[slot] = lightIndex;
+            scratch.staleRun[slot] = 0;
+        }
+        const run = stale ? Math.min((scratch.staleRun[slot] ?? 0) + 1, CHRONIC_STALE_FRAMES) : 0;
+        scratch.staleRun[slot] = run;
+        scratch.chronic[slot] = run >= CHRONIC_STALE_FRAMES ? 1 : 0;
+    }
+    const planned = planPointShadowBakes(scratch.stale, scratch.ready, count, scratch.order, scratch.chronic);
+    let faces = facesPerFrame;
+    let urgentSpent = false;
+    for (let i = 0; i < planned && faces > 0; i++) {
+        const slot = scratch.order[i] ?? -1;
+        /*
+         * `pooledLight`, matching the loop that filled `stale`: resolving through the sampled list
+         * here would bake the wrong light for every warm slot.
+         */
+        const lightIndex = slot >= 0 ? pool.pooledLight(slot) : -1;
+        const light = lightIndex >= 0 ? lights[lightIndex] : undefined;
+        const map = lightIndex >= 0 ? pool.mapForLight(lightIndex) : undefined;
+        if (light === undefined || map === undefined)
+            continue;
+        const cold = slot < pool.sampledCount && scratch.ready[slot] === 0;
+        const budget = cold && !urgentSpent ? faceCount : faces;
+        if (cold && !urgentSpent)
+            urgentSpent = true;
+        faces -= bake(map, light, staticCasters, budget);
+    }
+    /*
+     * Live maps contain movers only and are composed with the static maps in the shader. A second
+     * map exists only during an ownership crossfade.
+     *
+     * **Unlike a static map there is no staleness test to make** — the caster moved, that is what
+     * makes it live — **but there does have to be a ceiling, and there was not one.** This loop
+     * asked for the whole cubemap, per live map, every frame, outside `facesPerFrame` entirely.
+     * Measured on the consumer and on three of the engine's seven demos: `pointShadow.face`
+     * six times a frame, for ever, in scenes that were otherwise nine to fourteen passes. And
+     * `LIVE_POINT_SHADOW_MAPS` is two with the second waking up during an ownership handoff, which
+     * is precisely what running past a row of lamps is — so a courtyard paid twelve full passes over
+     * the dynamic casters a frame, which is where "it is only slow in the courtyard" came from.
+     *
+     * The faces round-robin under the budget instead, so a mover's shadow finishes over two or
+     * three frames rather than all inside one. What that costs is a shadow a frame or two behind
+     * a character. What it bought back was the frame rate to see it at all.
+     */
+    let liveFaces = Math.max(1, liveFacesPerFrame);
+    for (let slot = 0; slot < pool.liveMapCount && liveFaces > 0; slot++) {
+        const owner = pool.liveOwner(slot);
+        const light = owner >= 0 ? lights[owner] : undefined;
+        const map = pool.liveMap(slot);
+        if (light === undefined || map === undefined)
+            continue;
+        /* Never wider than the cube itself: asking for more is asking for faces that do not exist. */
+        liveFaces -= bake(map, light, dynamicCasters, Math.min(liveFaces, faceCount));
+    }
+}

package/dist/render/pointShadowImage.d.ts

@@ -0,0 +1,265 @@
+import { mat3, mat4 } from 'gl-matrix';
+/**
+ * What a point light's shadow cubemap *is*, with no device in it.
+ *
+ * **Everything here is a decision, and the six that matter are already paid for.** A cubemap
+ * that is stale by a millimetre re-bakes six passes over the world; one that is not stale
+ * enough strobes; one that publishes its parameters before its last face pairs new numbers with
+ * old pixels; one that keeps `baked` across a pool handover reports another lamp's picture as
+ * its own. Each of those was a shipped bug on the WebGL2 path and each is fixed *here*, so a
+ * second backend inherits the fixes instead of re-earning them. That is the 2026-08-13 rule
+ * applied to the largest piece of state in the renderer.
+ *
+ * The device half — the cube texture and the six passes that fill it — is per backend and is
+ * all that is left outside this file.
+ */
+/** A cubemap is six faces, and a bake may be spread across frames a few at a time. */
+export declare const FACE_COUNT = 6;
+/**
+ * Default distance from the source at which shadow casting begins.
+ *
+ * Raising it per light is how a fixture avoids shadowing its own lamp: a brazier sits directly
+ * under its flame, so with a near plane of a few centimetres it occludes an enormous solid
+ * angle and throws a big square across the ground. Anything nearer the source than this is
+ * simply not rendered into the map, which is what real fixtures do — the light comes from
+ * *inside* them.
+ */
+export declare const POINT_SHADOW_NEAR = 0.25;
+/**
+ * The emitter radius assumed for a light that names none.
+ *
+ * One constant because it is read in three places — the field, the bake and `matchesSource` —
+ * and the whole of the bug it replaces was two of those disagreeing. The bake filled in 0.05
+ * and `matchesSource` compared against `undefined`, so a map baked by a caller that said
+ * nothing was stale on every frame it was ever checked.
+ */
+export declare const DEFAULT_SOURCE_RADIUS = 0.05;
+/**
+ * One face's view-projection, into a matrix the caller owns.
+ *
+ * A ninety-degree square frustum per face is what makes six of them a cube, so the projection
+ * takes no aspect and no field of view: both are fixed by the shape. Module-scope scratch,
+ * because this runs once per face of every bake and `AGENTS.md` allows no allocation there.
+ */
+export declare function pointShadowFaceViewProj(face: number, x: number, y: number, z: number, near: number, range: number, out: mat4): mat4;
+/**
+ * A face's world-to-face rotation, from the same targets its frustum is built from.
+ *
+ * **The resolve needs one and the bake needs the other, and two tables would eventually
+ * disagree.** A face's octahedral region is written by projecting each texel's direction into that
+ * face's own frame and reading the depth the bake stored there; if the two differ by an up vector,
+ * every texel of that face is read from the wrong place. That reads as a lighting bug and is a
+ * transcription error, so both come off `FACE_TARGETS` and a test puts one point through each and
+ * requires the same image coordinates.
+ *
+ * `lookAt` builds a right-handed view looking down `-z`, so a direction inside this face comes
+ * back with a **negative** `z`. The resolve divides by `-v.z` for that reason and not by
+ * preference.
+ *
+ * Module-scope scratch, because this runs once per resolved face inside the bake budget and
+ * `AGENTS.md` allows no allocation there.
+ */
+export declare function pointShadowFaceRotation(face: number, out: mat3): mat3;
+/**
+ * The window of faces a resumed bake should render this frame, and what to render them for.
+ * Empty when there is none.
+ *
+ * **The parameters travel with the window, and that is the point rather than a convenience.**
+ * A bake is spread over frames against `pointShadowBudget.ts`, and a caller that used its own
+ * live light position for the second half would build an image around two different places —
+ * which is the failure `planBake` says it exists to prevent and, before these fields, did not.
+ * See `planBake`.
+ */
+export interface FaceRange {
+    first: number;
+    last: number;
+    /** Where the light was when this bake started. */
+    x: number;
+    y: number;
+    z: number;
+    /** The far plane, the near plane and the emitter radius the same bake started with. */
+    range: number;
+    near: number;
+    sourceRadius: number;
+}
+/** A `FaceRange` a map can own for the life of the session, since a bake allocates nothing. */
+export declare function createFaceRange(): FaceRange;
+/**
+ * The state of one cubemap: what it was baked for, how present it is, and how far through.
+ *
+ * Held by a backend's map rather than inherited from, so the device resource stays a device
+ * resource and this stays testable without one.
+ */
+export declare class PointShadowImage {
+    /** Far plane, needed by the shader to linearise the comparison. */
+    far: number;
+    /** Near plane; the shader needs the same value to linearise. */
+    near: number;
+    /** Emitter radius of the light this map was baked for. */
+    sourceRadius: number;
+    private baked;
+    private arrival;
+    private x;
+    private y;
+    private z;
+    /** Next face a resumed bake will render; 0 when none is in flight. */
+    private pendingFace;
+    /** What the in-flight bake was started for, so a changed light restarts it. */
+    private pendingX;
+    private pendingY;
+    private pendingZ;
+    private pendingRange;
+    private pendingNear;
+    private pendingSourceRadius;
+    /** Whether this map holds an image worth sampling. False until a bake completes. */
+    get hasBaked(): boolean;
+    /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */
+    get presence(): number;
+    /**
+     * Whether this map still represents the source projection well enough to sample.
+     *
+     * `tolerance` is how far the source may drift from where it was baked before the map is
+     * stale. It exists because an exact comparison made a *flame* the most expensive object in
+     * the scene: a brazier wanders a few centimetres every frame to look alive, every frame that
+     * moved the light, and every move re-baked six cubemap faces of the entire static world. Up
+     * to eight sampled lights doing that is where a frame's 174 surplus draw calls came from,
+     * against an `AGENTS.md` budget of a hundred in total.
+     *
+     * A drift tolerance is the honest fix rather than a cheat. The shadow of static geometry
+     * metres away barely moves when the emitter shifts by centimetres, and a fire's shadow that
+     * re-solves every frame reads as strobing rather than as flicker. Callers that genuinely move
+     * a light pass 0 and get the old behaviour, because drift is measured against the *baked*
+     * origin and so accumulates rather than being forgiven each frame.
+     *
+     * `sourceRadius` defaults to exactly what a bake defaults it to, and the two defaults being
+     * one constant is the point rather than a convenience: they disagreed once, `0.05 !== undefined`
+     * was true every frame, every map was stale forever, and with a couple of faces of budget the
+     * only thing on screen was whichever face had most recently finished — a hard square of shadow
+     * that moved as you did. Any default would do as long as it is the same one. Two is the bug.
+     */
+    matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius?: number, tolerance?: number): boolean;
+    /**
+     * Ramp the image in over `ARRIVAL_SECONDS`.
+     *
+     * The drastic case, and the one the light's own fade cannot reach. A light leaving takes its
+     * shadow with it, because by the time membership changes the light is already at nothing —
+     * but a light *keeping* its place can still lose its picture, when a pool slot changes hands
+     * and `forget` throws the image away. The re-bake then lands whole between two frames, under
+     * a lamp that has not moved, and a shadow switching on is exactly as wrong as one switching
+     * off.
+     *
+     * Only a first image after a `forget` ramps. A map that merely drifted past the rebake
+     * tolerance keeps `baked` true throughout and stays fully present, which is right: it is
+     * correcting a picture, not arriving with one.
+     */
+    advance(dt: number): void;
+    /**
+     * Throw away the image, because this map is about to belong to another light.
+     *
+     * A pool slot keeps its cubemap when it changes hands. Without this, `baked` stayed true from
+     * the previous borrower, so the new light reported an image it had never rendered — the *old*
+     * lamp's, taken from somewhere else — and the shader sampled it for the three frames a
+     * re-bake takes at two faces each. That is the flicker: shadows and glare appearing and
+     * disappearing as the camera moves and the chosen eight reorder.
+     *
+     * The partial-bake cursor goes too: a resumed bake must not stitch new faces onto the
+     * previous light's old ones. Presence goes with the image — whatever arrives next is a new
+     * light's, and it arrives as one.
+     */
+    forget(): void;
+    /**
+     * Which faces to render now, and what to render them for.
+     *
+     * **A bake in flight owns its parameters until it finishes**, and the returned range carries
+     * them so the caller renders the remaining faces at the place the first ones were rendered
+     * for. Half a cubemap around one point and half around another is not a cubemap around
+     * anything, and this is what stops it being built.
+     *
+     * **It used to abandon a partial image whenever any argument moved, and that is the defect
+     * this replaces.** The comparison was exact — position, range, near plane and emitter radius,
+     * all of them — so a light that changes by any amount between two frames could never satisfy
+     * it. Two kinds are ordinary rather than exotic: a flame wanders a few centimetres every
+     * frame to look alive, and a light whose brightness is expressed as a radius rescales that
+     * radius every frame while it pulses. For either, `pendingFace` was reset to zero on every
+     * frame, so with a budget of two faces the bake rendered faces 0 and 1 for ever and **faces 2
+     * to 5 were never written again**.
+     *
+     * That is not a bake that is merely slow. `resolveFace` writes each face into the light's
+     * octahedral layer as it is rendered, and `hasBaked` stays true from the last bake that did
+     * complete — so the shader keeps sampling a layer holding two faces from where the light is
+     * now and four from wherever it used to be, permanently, at full presence. A cube face is a
+     * 90 degree frustum, so what that draws is a hard-edged quadrilateral of shadow standing on
+     * the ground under the lamp with nothing above it to cast one. Reported as exactly that.
+     *
+     * A light that moves during a bake is not lost: the image completes at the origin it started
+     * from, `matchesSource` finds it stale on the next frame, and a fresh bake starts. What it
+     * costs is a shadow up to `FACE_COUNT / facesPerFrame` frames behind a moving lamp, which is
+     * the trade `pointShadowRebakeDistance` already makes in a coarser form.
+     */
+    planBake(x: number, y: number, z: number, range: number, near: number, sourceRadius: number, maxFaces: number, out: FaceRange): FaceRange;
+    /**
+     * Record that faces up to `last` have been rendered.
+     *
+     * **`far`, `near` and `sourceRadius` move only when the last face lands**, and that is the
+     * one subtle part. They describe the image the shader is sampling, so publishing them early
+     * would pair new parameters with faces that are still mostly old. A first bake is not sampled
+     * at all until it completes, so this only matters for a re-bake, where holding the old values
+     * keeps them matched to the old faces.
+     */
+    completeBake(last: number, x: number, y: number, z: number, range: number, near: number, sourceRadius: number): void;
+}
+/**
+ * What a pool needs of a cubemap, whichever device holds it.
+ *
+ * Nine members, seven of which are `PointShadowImage`'s already — so a backend's map is this
+ * interface plus a texture and a way to fill it. Declared here rather than in either backend
+ * because `PointShadowSystem` and `LivePointShadowSet` are written against it, and a pool that
+ * knew which device it was pooling would be two pools.
+ */
+export interface PointShadowSource {
+    /** Which layer of the shared array holds this map's image. */
+    readonly layer: number;
+    readonly far: number;
+    readonly near: number;
+    readonly sourceRadius: number;
+    /** Whether this map holds an image worth sampling. */
+    readonly hasBaked: boolean;
+    /** How present the image is, 0 to 1. */
+    readonly presence: number;
+    advance(dt: number): void;
+    forget(): void;
+}
+/**
+ * Everything the shader needs about the point-shadow set, chosen once and bound twice.
+ *
+ * **The arrays are the decision and the textures are the binding**, which is the split the
+ * 2026-08-13 rule asks for. Which light owns which slot, whether its image has landed, and how
+ * present it is are answers a pool computes; turning them into `uniform1fv` or into bytes of a
+ * uniform block is all that differs between the backends.
+ *
+ * A caller owns one of these and hands it in, because this is filled every frame.
+ */
+export interface ResolvedPointShadows {
+    /**
+     * Per shaded light: which array layer holds its static shadow, or −1 for none.
+     *
+     * **Indexed by the shading pass's light, and it used to be the other way round.** When each
+     * map was its own `samplerCube` the shader could not index one, so it ran ten `else if` arms
+     * comparing a light against a slot's owner; every array here was addressed by the slot and the
+     * light was the value. One array texture makes the map a number, so the light can be the index
+     * and the whole chain becomes a lookup. Every array below moved with it.
+     */
+    readonly layers: Int32Array;
+    readonly far: Float32Array;
+    readonly near: Float32Array;
+    readonly sourceRadius: Float32Array;
+    /** How present each bound map is, so a re-baked one arrives rather than appears. */
+    readonly presence: Float32Array;
+    /** The live pair, by the same light index: a light owns at most one of the two. */
+    readonly liveLayers: Int32Array;
+    readonly liveFar: Float32Array;
+    readonly liveNear: Float32Array;
+    readonly liveSourceRadius: Float32Array;
+    readonly liveWeights: Float32Array;
+}
+export declare function createResolvedPointShadows(lights: number): ResolvedPointShadows;