@jgengine/shell 0.34.0 → 0.35.0

package/dist/render/crowdRegistry.js

@@ -1,5 +1,5 @@
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
-/** Below this ground speed a crowd character idles; a walk until the run speed. */
+/** Below this ground speed a crowd character idles when its model declares no walk speed. */
 const WALK_CLIP_SPEED = 0.25;
 const RUN_CLIP_SPEED = 2.6;
 /**
@@ -10,18 +10,34 @@ const RUN_CLIP_SPEED = 2.6;
 export function crowdKindOf(model) {
     return `${model.url}\u0000${model.targetHeight ?? 0}\u0000${model.scale ?? 1}\u0000${JSON.stringify(model.material ?? null)}`;
 }
-/** Whether a model can leave its own rig for the GPU crowd path: a rigged, clip-played, plain model. */
+/**
+ * Whether a model can leave its own rig for the GPU crowd path: one whose drawn result a batch can
+ * reproduce. A rigged, clip-played, plain model qualifies, and so does a model with no animation at
+ * all (a static crowd character) — it has no playback to lose. A model that needs per-entity
+ * materials, wind, hidden nodes, IK, attachments or a part composition keeps its own rig.
+ */
 export function crowdEligible(model) {
     if (model === undefined || model.lod === false)
         return false;
     if (model.ik !== undefined || model.attachments !== undefined || model.parts !== undefined)
         return false;
-    return model.animation !== undefined && model.animation !== "none";
+    if (model.partMotion !== undefined)
+        return false;
+    if (model.wind !== undefined && model.wind !== false)
+        return false;
+    if (model.surfaceDetail === false)
+        return false;
+    if ((model.materialAssignments?.length ?? 0) > 0)
+        return false;
+    if (model.hiddenNodes !== undefined && !(Array.isArray(model.hiddenNodes) && model.hiddenNodes.length === 0))
+        return false;
+    return true;
 }
 /**
  * The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty
- * when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own
- * rig instead of drawing a frozen crowd copy.
+ * when the model plays no clips at all (a static character) or when the rig's clip names do not
+ * resolve to locomotion roles, which leaves the character on its own rig instead of drawing a frozen
+ * crowd copy.
  */
 export function crowdClipsOf(model, clipNames) {
     const animation = resolveAnimationConfig(model.animation, clipNames);
@@ -33,13 +49,29 @@ export function crowdClipsOf(model, clipNames) {
     }
     return clips;
 }
-/** The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them. */
-export function crowdClipForSpeed(clips, speed) {
+/**
+ * The ground speeds the model's own locomotion graph switches clips at, so a batched character walks
+ * and idles at the same speed its own rig would. A model that declares none keeps the engine's
+ * defaults.
+ */
+export function crowdSpeedBandsOf(model, clipNames) {
+    const states = resolveAnimationConfig(model.animation, clipNames)?.states;
+    const band = (value, fallback) => value !== undefined && Number.isFinite(value) && value >= 0 ? value : fallback;
+    const walk = band(states?.walkSpeed, WALK_CLIP_SPEED);
+    return { walk, run: Math.max(band(states?.runSpeed, RUN_CLIP_SPEED), walk) };
+}
+/**
+ * The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf}
+ * orders them. `bands` is the model's own walk/run speed.
+ */
+export function crowdClipForSpeed(clips, speed, bands) {
     if (clips.length === 0)
         return undefined;
-    if (speed >= RUN_CLIP_SPEED)
+    const walk = bands?.walk ?? WALK_CLIP_SPEED;
+    const run = bands?.run ?? RUN_CLIP_SPEED;
+    if (speed >= run)
         return clips[2] ?? clips[1] ?? clips[0];
-    if (speed >= WALK_CLIP_SPEED)
+    if (speed >= walk)
         return clips[1] ?? clips[0];
     return clips[0];
 }
@@ -60,9 +92,55 @@ export function crowdKindReady(kind) {
  * The characters the crowd layer is currently drawing, written by their entity markers each frame.
  * It holds poses rather than React state: 71 pedestrians writing matrices must not re-render the
  * world, and the crowd batch reads the same entries back to fill its instance buffers.
+ *
+ * A marker asks {@link claim} for a slot; the batch declares how many it can draw, so a full batch
+ * leaves the rest of its kind on their own rigs. The registry keeps drawn ids in claim order, which
+ * is the instance order the batch writes, so a character leaving compacts the rest instead of
+ * leaving a stale matrix behind.
  */
 export class CharacterCrowdRegistry {
     members = new Map();
+    capacities = new Map();
+    geometries = new Map();
+    /** Declare how many characters one kind's batch can draw; `undefined` clears the batch. */
+    setCapacity(kind, capacity) {
+        if (capacity === undefined)
+            this.capacities.delete(kind);
+        else
+            this.capacities.set(kind, Math.max(0, Math.floor(capacity)));
+    }
+    /** How many characters one kind's batch can draw; zero until its batch mounts. */
+    capacity(kind) {
+        return this.capacities.get(kind) ?? 0;
+    }
+    /** Record the geometry and placement a batch draws its kind with, for picking. */
+    setGeometry(kind, geometry) {
+        if (geometry === undefined)
+            this.geometries.delete(kind);
+        else
+            this.geometries.set(kind, geometry);
+    }
+    /** The drawn geometry of one kind, once its batch is ready. */
+    geometry(kind) {
+        return this.geometries.get(kind);
+    }
+    /**
+     * Hand a character to the batch. Returns false when the batch is full, and the caller then keeps
+     * that character on its own rig. An existing member always updates.
+     */
+    claim(id, kind, member) {
+        const existing = this.members.get(id);
+        if (existing !== undefined && existing.kind === kind) {
+            Object.assign(existing.member, member);
+            return true;
+        }
+        if (existing === undefined && this.count(kind) >= this.capacity(kind))
+            return false;
+        if (existing !== undefined)
+            this.members.delete(id);
+        this.members.set(id, { kind, member: { ...member } });
+        return true;
+    }
     /** Record the pose an entity is showing as a crowd instance this frame. */
     set(id, kind, member) {
         const existing = this.members.get(id);
@@ -76,6 +154,10 @@ export class CharacterCrowdRegistry {
     delete(id) {
         this.members.delete(id);
     }
+    /** The kind this character is batched as, or `undefined` when it draws its own rig. */
+    kindOf(id) {
+        return this.members.get(id)?.kind;
+    }
     /** How many characters this kind is drawing; zero means the batch can skip its work. */
     count(kind) {
         let count = 0;
@@ -93,5 +175,6 @@ export class CharacterCrowdRegistry {
     /** Drop every entry; called when the crowd layer unmounts. */
     clear() {
         this.members.clear();
+        this.geometries.clear();
     }
 }

package/dist/render/shaderWarmup.d.ts

@@ -1,4 +1,4 @@
-import type { Camera, Object3D } from "three";
+import { type Camera, type Object3D } from "three";
 /**
  * Where the load-time shader warmup is: waiting for the scene to stop growing, compiling a
  * round, finished, or skipped because the renderer refused. The loading screen renders it.
@@ -9,6 +9,10 @@ export interface ShaderWarmupState {
     rounds: number;
     /** Shader programs the renderer has initialised, as of the last round. */
     programs: number;
+    /** Drawables the first frame can reach; these are compiled before the first frame is shown. */
+    planned: number;
+    /** Drawables the first frame cannot reach; compiled in the background after the reveal. */
+    deferred: number;
     elapsedMs: number;
 }
 /** The renderer surface the warmup needs; a real `WebGLRenderer` satisfies it. */
@@ -19,17 +23,56 @@ export interface ShaderWarmupRenderer {
     readonly info?: {
         readonly programs?: readonly unknown[] | null;
     };
+    /** The render target currently bound, if any; three builds different programs for a target. */
+    getRenderTarget?(): unknown;
+    /** Bind a render target, or `null` for the canvas. */
+    setRenderTarget?(target: unknown | null): void;
 }
-/** Defaults sized to cover an initial burst of streamed models without holding the screen. */
+/** Knobs for {@link planFirstFrame}; the defaults are what a normal load wants. @internal */
+export interface FirstFramePlanOptions {
+    /** Bounding-sphere growth for the view test, so a prop just offscreen stays in the plan. */
+    viewMargin?: number;
+}
+/** Which drawables the first frame can reach, so the cover waits for those and no others. @internal */
+export interface FirstFramePlan {
+    /** Drawables compiled before the first frame is shown. */
+    objects: ReadonlySet<Object3D>;
+    /** How many drawables the plan covers. */
+    reachable: number;
+    /** Drawables outside the first frame's reach, for the background compile. */
+    deferred: number;
+}
+/**
+ * The drawables the first frame can reach: shown, on a layer the camera renders, and either
+ * inside the view or a shadow caster, which the shadow pass draws without the camera seeing it.
+ *
+ * An object just outside the frame still counts, because a turned camera makes it visible before
+ * any background compile finishes; the view is grown by {@link FirstFramePlanOptions.viewMargin}.
+ * @internal
+ */
+export declare function planFirstFrame(scene: Object3D, camera: Camera, options?: FirstFramePlanOptions): FirstFramePlan;
+/**
+ * Links the programs of the drawables the predicate keeps, and nothing else: three has no
+ * per-object compile, so the rest is lifted out of the graph for the length of the synchronous
+ * call and put back exactly where it was. Same objects, so the programs are the ones a draw
+ * would build, which a cloned stand-in scene cannot promise.
+ * @internal
+ */
+export declare function compileSubset(renderer: ShaderWarmupRenderer, scene: Object3D, camera: Camera, keep: (object: Object3D) => boolean): void;
+/** Defaults sized to cover one load: the covered wait is the driver's link time, not a guess. */
 export declare const SHADER_WARMUP_DEFAULTS: {
-    /** Loader quiet time after which a round is the last one. */
-    readonly quietMs: 400;
-    /** Wall-clock cap on the whole warmup. The last round is cut off at it. */
-    readonly budgetMs: 5000;
-    /** Floor for a single round, so a driver that never reports completion cannot stall load. */
-    readonly roundFloorMs: 1500;
-    /** A scene still streaming after this long gets one last round and is revealed anyway. */
-    readonly streamWaitMs: 2000;
+    /** Loader and program quiet time before the first frame is shown. */
+    readonly quietMs: 250;
+    /** Wall-clock cap on the covered wait. The reveal happens at it either way. */
+    readonly planBudgetMs: 12000;
+    /** Floor for one wait, so a driver that never reports completion cannot stall load. */
+    readonly planFloorMs: 1500;
+    /** How often the covered loop looks for content that streamed in while it waited. */
+    readonly pollMs: 100;
+    /** How long the background compile keeps looking for content that landed after the reveal. */
+    readonly backgroundMs: 2000;
+    /** Gap between background rounds. A round only queues links; it does not wait on the driver. */
+    readonly backgroundEveryMs: 250;
 };
 /** Options for {@link createShaderWarmup}; the clock, sleep and loader signal are injectable for tests. */
 export interface ShaderWarmupOptions {
@@ -37,8 +80,10 @@ export interface ShaderWarmupOptions {
     scene: Object3D;
     camera: Camera;
     quietMs?: number;
-    budgetMs?: number;
-    streamWaitMs?: number;
+    planBudgetMs?: number;
+    pollMs?: number;
+    backgroundMs?: number;
+    backgroundEveryMs?: number;
     /** Called on every state change, so the loading screen can show the phase. */
     onState?: (state: ShaderWarmupState) => void;
     now?: () => number;
@@ -47,6 +92,14 @@ export interface ShaderWarmupOptions {
     loaderQuiet?: (quietMs: number) => boolean;
     /** Changes whenever the shared loader starts a new burst of model loads. */
     loaderStarts?: () => number;
+    /**
+     * Whether the frame that follows the cover draws the scene into a render target instead of the
+     * canvas, asked again on every round. three builds different programs for the two: a target
+     * renders linear with no tone map, the canvas renders in the output colour space with one. The
+     * warmup compiles against the one the frame will draw with, so it no longer links a set that
+     * nothing draws.
+     */
+    sceneDrawsToTarget?: () => boolean;
 }
 /** A warmup in flight: its promise, its latest state, and a way to stop it. */
 export interface ShaderWarmup {
@@ -57,13 +110,17 @@ export interface ShaderWarmup {
     cancel(): void;
 }
 /**
- * Warm the scene's shaders through the renderer's async compile, one round per burst of
- * streamed models, so materials first seen during load never compile on a visible frame.
+ * Compile what the first frame can reach, show it, then finish the rest in the background.
+ *
+ * The canvas does not draw while this runs (the loading cover holds it), so the driver links the
+ * first frame's programs in parallel with the scene still mounting, and nothing waits on a link
+ * from inside a frame. The covered wait ends when a round finds no new program and the model
+ * loader has gone quiet, so a scene that streams for seconds no longer holds the cover for all of
+ * it. Everything the first frame cannot reach is compiled in background rounds afterwards: those
+ * objects are not on screen, so their links never land on a drawing frame.
  *
- * A round is `compileAsync` over the mounted scene; the round after it runs only when the
- * model loader started a new burst or the program count grew, which is what a scene that is
- * still streaming looks like. Everything is bounded: the last round is raced against the
- * budget, so a driver that never reports a finished program cannot hold the loading screen.
+ * Everything is bounded: the reveal is raced against the plan budget, so a driver that never
+ * reports a finished program cannot hold the loading screen.
  * @internal
  */
 export declare function createShaderWarmup(options: ShaderWarmupOptions): ShaderWarmup;

package/dist/render/shaderWarmup.js

@@ -1,3 +1,4 @@
+import { Frustum, Matrix4, Sphere, Vector3, WebGLRenderTarget } from "three";
 import { modelLoadIdleMs, modelLoadStarts } from "./modelLoad.js";
 function programReady(program) {
     try {
@@ -7,107 +8,262 @@ function programReady(program) {
         return true;
     }
 }
-/** Defaults sized to cover an initial burst of streamed models without holding the screen. */
+function isDrawable(object) {
+    const candidate = object;
+    if (candidate.material === undefined)
+        return false;
+    return candidate.isMesh === true || candidate.isPoints === true || candidate.isLine === true || candidate.isSprite === true;
+}
+const DEFAULT_VIEW_MARGIN = 1.4;
+/**
+ * The drawables the first frame can reach: shown, on a layer the camera renders, and either
+ * inside the view or a shadow caster, which the shadow pass draws without the camera seeing it.
+ *
+ * An object just outside the frame still counts, because a turned camera makes it visible before
+ * any background compile finishes; the view is grown by {@link FirstFramePlanOptions.viewMargin}.
+ * @internal
+ */
+export function planFirstFrame(scene, camera, options = {}) {
+    const margin = options.viewMargin ?? DEFAULT_VIEW_MARGIN;
+    scene.updateMatrixWorld();
+    camera.updateMatrixWorld();
+    const frustum = new Frustum();
+    frustum.setFromProjectionMatrix(new Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse));
+    const objects = new Set();
+    let deferred = 0;
+    const visit = (object, shownByParent) => {
+        const shown = shownByParent && object.visible;
+        if (isDrawable(object)) {
+            if (shown && inReach(object, camera, frustum, margin))
+                objects.add(object);
+            else
+                deferred += 1;
+        }
+        for (const child of object.children)
+            visit(child, shown);
+    };
+    visit(scene, true);
+    return { objects, reachable: objects.size, deferred };
+}
+function inReach(object, camera, frustum, margin) {
+    if (!object.layers.test(camera.layers))
+        return false;
+    if (object.frustumCulled === false)
+        return true;
+    const geometry = object.geometry;
+    if (geometry !== undefined && geometry.boundingSphere === null)
+        geometry.computeBoundingSphere();
+    const sphere = geometry?.boundingSphere ?? null;
+    if (sphere === null)
+        return true;
+    // A caster outside the view is still drawn by the shadow pass, so its program is needed too.
+    if (object.castShadow === true)
+        return true;
+    const position = object.getWorldPosition(new Vector3());
+    const grown = new Sphere().copy(sphere).translate(position);
+    grown.radius = sphere.radius * margin;
+    return frustum.intersectsSphere(grown);
+}
+/**
+ * Links the programs of the drawables the predicate keeps, and nothing else: three has no
+ * per-object compile, so the rest is lifted out of the graph for the length of the synchronous
+ * call and put back exactly where it was. Same objects, so the programs are the ones a draw
+ * would build, which a cloned stand-in scene cannot promise.
+ * @internal
+ */
+export function compileSubset(renderer, scene, camera, keep) {
+    const lifted = [];
+    const walk = (object) => {
+        for (const child of [...object.children]) {
+            if (isDrawable(child) && !keep(child)) {
+                lifted.push({ parent: object, index: object.children.indexOf(child), object: child });
+                object.children.splice(object.children.indexOf(child), 1);
+                child.parent = null;
+                continue;
+            }
+            walk(child);
+        }
+    };
+    walk(scene);
+    try {
+        renderer.compile(scene, camera);
+    }
+    finally {
+        for (const { parent, index, object } of lifted.sort((a, b) => a.index - b.index)) {
+            parent.children.splice(Math.min(index, parent.children.length), 0, object);
+            object.parent = parent;
+        }
+    }
+}
+/** Defaults sized to cover one load: the covered wait is the driver's link time, not a guess. */
 export const SHADER_WARMUP_DEFAULTS = {
-    /** Loader quiet time after which a round is the last one. */
-    quietMs: 400,
-    /** Wall-clock cap on the whole warmup. The last round is cut off at it. */
-    budgetMs: 5_000,
-    /** Floor for a single round, so a driver that never reports completion cannot stall load. */
-    roundFloorMs: 1_500,
-    /** A scene still streaming after this long gets one last round and is revealed anyway. */
-    streamWaitMs: 2_000,
+    /** Loader and program quiet time before the first frame is shown. */
+    quietMs: 250,
+    /** Wall-clock cap on the covered wait. The reveal happens at it either way. */
+    planBudgetMs: 12_000,
+    /** Floor for one wait, so a driver that never reports completion cannot stall load. */
+    planFloorMs: 1_500,
+    /** How often the covered loop looks for content that streamed in while it waited. */
+    pollMs: 100,
+    /** How long the background compile keeps looking for content that landed after the reveal. */
+    backgroundMs: 2_000,
+    /** Gap between background rounds. A round only queues links; it does not wait on the driver. */
+    backgroundEveryMs: 250,
 };
 /**
- * Warm the scene's shaders through the renderer's async compile, one round per burst of
- * streamed models, so materials first seen during load never compile on a visible frame.
+ * Compile what the first frame can reach, show it, then finish the rest in the background.
+ *
+ * The canvas does not draw while this runs (the loading cover holds it), so the driver links the
+ * first frame's programs in parallel with the scene still mounting, and nothing waits on a link
+ * from inside a frame. The covered wait ends when a round finds no new program and the model
+ * loader has gone quiet, so a scene that streams for seconds no longer holds the cover for all of
+ * it. Everything the first frame cannot reach is compiled in background rounds afterwards: those
+ * objects are not on screen, so their links never land on a drawing frame.
  *
- * A round is `compileAsync` over the mounted scene; the round after it runs only when the
- * model loader started a new burst or the program count grew, which is what a scene that is
- * still streaming looks like. Everything is bounded: the last round is raced against the
- * budget, so a driver that never reports a finished program cannot hold the loading screen.
+ * Everything is bounded: the reveal is raced against the plan budget, so a driver that never
+ * reports a finished program cannot hold the loading screen.
  * @internal
  */
 export function createShaderWarmup(options) {
     const quietMs = options.quietMs ?? SHADER_WARMUP_DEFAULTS.quietMs;
-    const budgetMs = options.budgetMs ?? SHADER_WARMUP_DEFAULTS.budgetMs;
-    const streamWaitMs = options.streamWaitMs ?? SHADER_WARMUP_DEFAULTS.streamWaitMs;
+    const planBudgetMs = options.planBudgetMs ?? SHADER_WARMUP_DEFAULTS.planBudgetMs;
+    const pollMs = options.pollMs ?? SHADER_WARMUP_DEFAULTS.pollMs;
+    const backgroundMs = options.backgroundMs ?? SHADER_WARMUP_DEFAULTS.backgroundMs;
+    const backgroundEveryMs = options.backgroundEveryMs ?? SHADER_WARMUP_DEFAULTS.backgroundEveryMs;
     const now = options.now ?? (() => performance.now());
     const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     const loaderQuiet = options.loaderQuiet ?? ((quiet) => modelLoadIdleMs() >= quiet);
     const loaderStarts = options.loaderStarts ?? modelLoadStarts;
     const startedAt = now();
-    let state = { phase: "waiting", rounds: 0, programs: 0, elapsedMs: 0 };
+    let state = { phase: "waiting", rounds: 0, programs: 0, planned: 0, deferred: 0, elapsedMs: 0 };
     let cancelled = false;
     const programs = () => options.renderer.info?.programs?.length ?? 0;
-    const publish = (next) => {
-        state = { ...state, ...next, elapsedMs: Math.round(now() - startedAt) };
-        options.onState?.(state);
+    // Any target builds the same programs: three reads "rendering to a target" for the colour space
+    // and the tone map, not the target's size or format.
+    let scratchTarget = null;
+    const frameTarget = () => {
+        if (options.sceneDrawsToTarget?.() !== true)
+            return null;
+        scratchTarget ??= new WebGLRenderTarget(1, 1);
+        return scratchTarget;
+    };
+    const releaseScratch = () => {
+        scratchTarget?.dispose();
+        scratchTarget = null;
     };
-    const compileRound = async () => {
-        const remaining = budgetMs - (now() - startedAt);
-        const allowance = Math.max(SHADER_WARMUP_DEFAULTS.roundFloorMs, remaining);
-        const deadline = now() + allowance;
-        const before = options.renderer.info?.programs?.length ?? 0;
+    /** Compile with the frame's target bound, so the links are the programs that frame draws. */
+    const withFrameTarget = (compile) => {
+        const target = frameTarget();
+        const renderer = options.renderer;
+        if (target === null || renderer.setRenderTarget === undefined) {
+            compile();
+            return;
+        }
+        const previous = renderer.getRenderTarget?.() ?? null;
+        renderer.setRenderTarget(target);
         try {
-            // `compileAsync` reports readiness through three's private program property, which throws
-            // when a material regenerated its program mid-poll (ember-command does). Poll the public
-            // program list instead: same wait, no crash path.
-            options.renderer.compile(options.scene, options.camera);
+            compile();
         }
-        catch {
-            return "error";
+        finally {
+            renderer.setRenderTarget(previous);
         }
+    };
+    const publish = (next) => {
+        state = { ...state, ...next, elapsedMs: Math.round(now() - startedAt) };
+        options.onState?.(state);
+    };
+    /** Wait for the programs a round created, polling readiness so the thread stays free to mount. */
+    const settle = async (from, deadline) => {
+        let polls = 0;
         for (;;) {
             if (cancelled)
-                return "timeout";
-            const programs = options.renderer.info?.programs?.slice(before) ?? [];
-            if (programs.every(programReady))
-                return "compiled";
+                return false;
+            const created = options.renderer.info?.programs?.slice(from) ?? [];
+            if (created.every(programReady))
+                return true;
             if (now() >= deadline)
-                return "timeout";
+                return false;
+            if (polls++ % 20 === 0)
+                publish({ programs: programs() });
             await sleep(10);
         }
     };
-    /** Wait (bounded) for the loader to go quiet, so a round is the last one when nothing is left. */
-    const waitLoaderQuiet = async (limitMs) => {
-        const until = startedAt + budgetMs;
-        const limit = Math.min(limitMs, until - now());
-        if (loaderQuiet(quietMs))
-            return true;
-        const deadline = now() + Math.max(0, limit);
-        while (!cancelled && now() < deadline) {
-            await sleep(100);
-            if (loaderQuiet(quietMs))
-                return true;
+    /** One covered round: plan the reachable set, queue its links, wait for them off the frame. */
+    const round = async (deadline) => {
+        const plan = planFirstFrame(options.scene, options.camera);
+        publish({ planned: plan.reachable, deferred: plan.deferred, programs: programs() });
+        const before = programs();
+        try {
+            withFrameTarget(() => compileSubset(options.renderer, options.scene, options.camera, (object) => plan.objects.has(object)));
         }
-        return loaderQuiet(quietMs);
+        catch {
+            return "error";
+        }
+        publish({ rounds: state.rounds + 1, programs: programs() });
+        const floor = now() + SHADER_WARMUP_DEFAULTS.planFloorMs;
+        await settle(before, Math.max(deadline, floor));
+        return "ok";
     };
-    const done = (async () => {
-        publish({ phase: "compiling" });
-        for (;;) {
+    /** Queue links for content that has no program yet, without waiting on the driver. */
+    const queueBackground = () => {
+        try {
+            withFrameTarget(() => options.renderer.compile(options.scene, options.camera));
+        }
+        catch {
+            /* a background round is an optimisation; the first frame is already showing */
+        }
+    };
+    /** Compile later content in rounds that never block the cover or the frame in flight. */
+    const background = async () => {
+        const until = now() + backgroundMs;
+        let quietRounds = 0;
+        while (!cancelled && now() < until) {
+            await sleep(backgroundEveryMs);
             if (cancelled)
                 break;
             const starts = loaderStarts();
-            const outcome = await compileRound();
-            if (outcome === "error") {
+            const before = programs();
+            queueBackground();
+            const grew = programs() > before || loaderStarts() !== starts;
+            quietRounds = grew ? 0 : quietRounds + 1;
+            publish({ programs: programs() });
+            if (quietRounds >= 2)
+                break;
+        }
+    };
+    const covered = async () => {
+        publish({ phase: "compiling" });
+        const deadline = startedAt + planBudgetMs;
+        let quietSince = now();
+        let previous = programs();
+        while (!cancelled) {
+            if ((await round(deadline)) === "error") {
                 publish({ phase: "failed" });
-                return state;
+                return false;
             }
             const settled = programs();
-            publish({ rounds: state.rounds + (outcome === "compiled" ? 1 : 0), programs: settled });
-            if (outcome === "timeout" || cancelled || now() - startedAt >= budgetMs)
-                break;
-            if (!(await waitLoaderQuiet(streamWaitMs)))
+            const grew = settled > previous;
+            previous = settled;
+            quietSince = grew ? now() : quietSince;
+            if (now() >= deadline)
                 break;
-            const streamed = loaderStarts() !== starts;
-            const linked = programs() > settled;
-            if (cancelled || (!streamed && !linked))
+            if (!grew && now() - quietSince >= quietMs && loaderQuiet(quietMs))
                 break;
-            if (now() - startedAt >= budgetMs)
+            await sleep(pollMs);
+            if (cancelled)
                 break;
         }
-        publish({ phase: "ready" });
+        // The reveal is the last draw boundary: everything the first frame shows has been settled
+        // above, so lifting the cover draws a scene with no program left to link mid-frame.
+        publish({ programs: programs(), phase: "ready" });
+        return true;
+    };
+    const done = (async () => {
+        if (!(await covered())) {
+            releaseScratch();
+            return state;
+        }
+        void background().finally(releaseScratch);
         return state;
     })();
     return {
@@ -115,6 +271,7 @@ export function createShaderWarmup(options) {
         state: () => state,
         cancel: () => {
             cancelled = true;
+            releaseScratch();
         },
     };
 }

package/dist/render/shadowCasters.d.ts

@@ -12,6 +12,7 @@ export interface ShadowCasterCull {
     stats(): {
         casters: number;
         skipped: number;
+        minRadius: number;
     };
     restore(): void;
 }

package/dist/render/shadowCasters.js

@@ -83,7 +83,7 @@ export function cullSmallShadowCasters(root, minRadius = MIN_SHADOW_CASTER_RADIU
                 if (node.isMesh === true && node.castShadow)
                     casters += 1;
             });
-            return { casters, skipped: cleared.size };
+            return { casters, skipped: cleared.size, minRadius };
         },
         restore() {
             for (const off of listeners.values())