fun buildRig(renderer: Renderer): Rig {
        val bundle = StandardRenderer.build(
            renderer,
            StandardRenderer.Config(
                renderWidth = DIM,
                renderHeight = DIM,
                backgroundColor = Vector3f(0.09f, 0.10f, 0.13f)
            )
        )
        val scene = bundle.scene

        // The square target must be projected square. `Projection(renderer)`'s `auto` lambda
        // re-resizes to the *window* inside every `evaluateUniform`, so a one-off `resize` is
        // overwritten on the next frame and a sphere in a 512² target inside a wide window comes
        // out as an ellipse — plausible enough to stare past. Replacing the lambda is the fix;
        // calling `resize` once is not.
        scene.projection.auto = { scene.projection.resize(DIM, DIM) }
        scene.projection.resize(DIM, DIM)

        scene.camera.at.set(0f, 2.0f, -3.2f)
        scene.camera.target.set(0f, 0f, 0f)
        scene.lightDirection.set(Vector3f(-0.5f, -1f, -0.3f).normalize())
        scene.lightIntensity = 3.4f
        scene.shadowStrength = 1f
        scene.aoStrength = 0.8f

        val spheres = buildList {
            for (ix in 0 until GRID) for (iz in 0 until GRID) {
                add(bundle.registerSphere(name = "ball-$ix-$iz", radius = 0.3f, slices = 24, stacks = 24, renderer = renderer))
            }
        }
        // A floor, and not for decoration: `shadow.strength` and `ao.strength` are two of the ten
        // lanes, and with nothing under the spheres to receive a shadow or an occlusion they were
        // two lanes a sweep could move all night without changing a pixel.
        bundle.registerCube(name = "floor", size = 1f, renderer = renderer)
            .setModel(Matrix4f().translate(0f, -0.33f, 0f).scale(11f, 0.04f, 11f))
        bundle.applyScenePlan()

        // Two lanes with CPU consequences rather than uniform ones: the grid's spacing, and how many
        // of its nine spheres are drawn at all. A hidden sphere is scaled to nothing, which is the
        // cheap way to make an `Int` lane change the geometry without rebuilding a mesh.
        var spread = 0.85f
        var visible = GRID * GRID

        // Hidden from the outside in, not from the end of the list. Hiding the tail of a row-major
        // grid takes its last row away and shoves the remaining cluster off to one side, so the
        // `visible` lane would be half a camera move as well as a count — and a blend of two looks
        // would drift across the frame for a reason nothing in the key names.
        val centreOut = (0 until GRID * GRID).sortedBy { i ->
            val ix = i / GRID - (GRID - 1) / 2
            val iz = i % GRID - (GRID - 1) / 2
            ix * ix + iz * iz
        }
        fun layout() {
            centreOut.forEachIndexed { rank, i ->
                val pair = spheres[i]
                if (rank >= visible) {
                    pair.setModel(Matrix4f().scale(0f))
                } else {
                    val ix = i / GRID - (GRID - 1) / 2
                    val iz = i % GRID - (GRID - 1) / 2
                    pair.setModel(Matrix4f().translate(ix * spread, 0f, iz * spread))
                }
            }
        }
        layout()

        var palette = "warm"
        fun applyPalette(name: String) {
            val (ambient, light) = palettes[name] ?: palettes.getValue("warm")
            scene.ambientColor.set(ambient)
            scene.lightColor.set(light)
            palette = name
        }
        applyPalette(palette)

        val scope = KeyframeScope(schemaVersion = 1).apply {
            vector3Target("camera.at", { scene.camera.at }) { scene.camera.at.set(it) }
            vector3Target("camera.target", { scene.camera.target }) { scene.camera.target.set(it) }
            vector3Target("light.direction", { scene.lightDirection }) {
                scene.lightDirection.set(if (it.lengthSquared() > 1e-8f) Vector3f(it).normalize() else it)
            }
            floatTarget("light.intensity", { scene.lightIntensity }) { scene.lightIntensity = it }
            vector3Target("background", { scene.backgroundColor }) { scene.backgroundColor.set(it) }
            floatTarget("ao.strength", { scene.aoStrength }) { scene.aoStrength = it }
            floatTarget("shadow.strength", { scene.shadowStrength }) { scene.shadowStrength = it }
            floatTarget("grid.spread", { spread }) { spread = it; layout() }
            intTarget("grid.visible", { visible }, 1..(GRID * GRID)) { visible = it; layout() }
            // The discrete lane: a name that selects a whole sub-state. There is no midpoint between
            // "warm" and "acid", which is exactly why a sweep takes it whole from one parent.
            stringTarget("palette", { palette }) { applyPalette(it) }
        }

        return Rig(bundle, scope, Vector3f(scene.camera.at))
    }

    fun writePool(scope: KeyframeScope, dir: Path): Int {
        dir.createDirectories()
        fun key(name: String, values: Map<String, Any?>) =
            dir.resolve(name).writeText(scope.encodeKeyJson(scope.Key(values.toMutableMap())))

        key(
            "high-and-cool", mapOf(
                "camera.at" to Vector3f(0f, 3.0f, -3.0f),
                "camera.target" to Vector3f(0f, 0f, 0f),
                "light.direction" to Vector3f(-0.5f, -1f, -0.3f).normalize(),
                "light.intensity" to 3.4f,
                "background" to Vector3f(0.012f, 0.020f, 0.050f),
                "ao.strength" to 0.85f,
                "shadow.strength" to 1.0f,
                "grid.spread" to 0.85f,
                "grid.visible" to 9,
                "palette" to "cool"
            )
        )
        key(
            "low-and-warm", mapOf(
                "camera.at" to Vector3f(1.8f, 1.2f, -2.6f),
                "camera.target" to Vector3f(0f, 0.1f, 0f),
                "light.direction" to Vector3f(0.7f, -0.4f, -0.5f).normalize(),
                "light.intensity" to 6.2f,
                "background" to Vector3f(0.050f, 0.025f, 0.012f),
                "ao.strength" to 0.35f,
                "shadow.strength" to 0.6f,
                "grid.spread" to 1.45f,
                "grid.visible" to 4,
                "palette" to "warm"
            )
        )
        key(
            "flat-and-acid", mapOf(
                "camera.at" to Vector3f(-2.2f, 1.8f, -2.4f),
                "camera.target" to Vector3f(0.2f, 0.2f, 0f),
                "light.direction" to Vector3f(-0.1f, -0.95f, 0.1f).normalize(),
                "light.intensity" to 1.9f,
                "background" to Vector3f(0.010f, 0.045f, 0.015f),
                "ao.strength" to 1.0f,
                "shadow.strength" to 0.15f,
                "grid.spread" to 0.55f,
                "grid.visible" to 9,
                "palette" to "acid"
            )
        )
        key(
            "older-partial-key", mapOf(
                "camera.at" to Vector3f(0f, 1.6f, -3.6f),
                "camera.target" to Vector3f(0f, 0f, 0f),
                "light.direction" to Vector3f(-0.8f, -0.6f, 0.1f).normalize(),
                "light.intensity" to 4.6f,
                "background" to Vector3f(0.020f, 0.020f, 0.020f),
                "shadow.strength" to 0.8f,
                "grid.spread" to 1.05f,
                "grid.visible" to 6
            )
        )
        return 4
    }

    fun main(args: Array<String>) {
        val keepOpen = args.contains("--keep")
        Options.enableVR = false
        Options.doVulkanSDK()

        outputDir.mkdirs()
        val window = Window("Field · Keyframe sweep")
        val renderer = Renderer(window)

        // `StandardRenderer.build` allocates targets through a bare `RenderToTexture { … }`, whose
        // renderer defaults to `fromContext()`, so it only works where a Box context can see one.
        // See FabricatePassChainDemo for what the failure looks like without this.
        val hostBox = Box("keyframe-sweep-demo").apply { name = "keyframe-sweep-demo" }
        hostBox.setPropertyRaw("renderer", renderer, doResync = false)
        hostBox.setPropertyRaw("window", window, doResync = false)

        try {
            Box.withBoxContextNow(hostBox) { run(renderer, window) }
            if (keepOpen) {
                println("-- --keep: leaving the window open, close it to exit --")
                while (!window.shouldClose()) pump(renderer, window, 1)
            }
        } catch (t: Throwable) {
            println("FAIL: ${t.message}")
            t.printStackTrace()
            failures++
        } finally {
            runCatching { renderer.cleanup() }
            runCatching { window.cleanup() }
        }

        if (failures == 0) println("keyframe sweep tests PASSED — archive in ${outputDir.absolutePath}")
        else println("keyframe sweep tests FAILED ($failures)")
        // GLFW and Vulkan leave non-daemon threads behind, so the JVM will not exit on its own.
        exitProcess(if (failures == 0) 0 else 1)
    }

    private fun run(renderer: Renderer, window: Window) {
        val rig = buildRig(renderer)
        rig.bundle.present(renderer = renderer)
        rig.bundle.attachTo(renderer)
        pump(renderer, window, WARMUP_FRAMES)

        val root = outputDir.toPath()
        val pool = root.resolve("pool")
        val out = root.resolve("archive")
        if (out.exists()) out.toFile().deleteRecursively()
        val poolSize = writePool(rig.scope, pool)
        check(poolSize == 4) { "the fixture pool should be four keys" }

        println("sweeping a pool of $poolSize keys:")
        val report = runBlocking {
            // A pump coroutine, so the sweep can wait in *frames* rather than in milliseconds — and
            // so `awaitFrames` is actually exercised here rather than only compiled.
            //
            // Inside Field the Runloop advances the renderer and a callback simply waits. A
            // standalone JVM has no Runloop, so the naive version of this deadlocks: the thread that
            // would render is the thread that is waiting to see a render. `runBlocking`'s dispatcher
            // is single-threaded and cooperative, so putting the pump in a sibling coroutine makes
            // `awaitFrames`'s own `delay`/`yield` hand it the thread — which reproduces the Runloop's
            // interleaving closely enough to test the real waiting path.
            val pump = launch {
                while (isActive) {
                    window.pollEvents()
                    renderer.render()
                    yield()
                }
            }
            try {
                sweep(
                    rig, renderer, pool, out,
                    SweepConfig(
                        seed = 20260916,
                        count = 6,
                        minArity = 2,
                        maxArity = 3,
                        concentration = 0.7,
                        extrapolationProbability = 0.34,
                        // A smoke run must not stop early for a reason the assertions would then
                        // blame on the sweeper, and it is writing tens of kilobytes, not gigabytes.
                        minFreeBytes = 64L shl 20
                    )
                ) { frames -> renderer.awaitFrames(frames) }
            } finally {
                pump.cancelAndJoin()
            }
        }
        println(report)
        expect(report.completed == 6, "six renders completed, not ${report.completed}")
        expect(report.failed == 0, "no render should have failed; ${report.failed} did")

        val rows = readSweepArchive(out)
        expect(rows.size == 6, "six manifests, not ${rows.size}")

        // Every render is complete on disk: the provenance, the key, and the picture.
        rows.forEach { m ->
            val dir = out.resolve("renders/${m.id}")
            expect(dir.resolve("key.json").exists(), "${m.id} has no key.json")
            expect(dir.resolve("manifest.json").exists(), "${m.id} has no manifest.json")
            expect(dir.resolve("still.png").exists(), "${m.id} has no still.png")
            expect(m.status == "ok", "${m.id} ended as ${m.status}")
            expect(
                m.artifacts.any { it.kind == "still" && it.file == "still.png" && it.bytes > 0 },
                "${m.id} did not record its still as an artifact"
            )
            val clip = m.artifacts.firstOrNull { it.kind == "clip" }
            expect(clip != null, "${m.id} recorded no clip artifact at all")
            val clipFile = clip?.file
            if (clipFile != null) {
                expect(dir.resolve(clipFile).exists(), "${m.id} recorded a clip that is not there")
            } else {
                // No ffmpeg on this machine is a stated gap, not a silent one — and the frames that
                // would have been muxed are still on disk for `muxSweepArchiveClips`.
                expect(clip?.note != null, "${m.id} has no clip and no reason")
                expect(dir.resolve("frames").exists(), "${m.id} has neither a clip nor its frames")
                println("  note: ${clip?.note}")
            }
            expect(
                dir.resolve("frames").toFile().listFiles()?.size?.let { it >= CLIP_FRAMES } != false,
                "${m.id} wrote fewer than $CLIP_FRAMES clip frames"
            )
        }

        // The back-fill really happened, on the one key that was written short.
        expect(
            rows.any { m -> m.parents.any { it.key == "older-partial-key" && it.filled.isNotEmpty() } },
            "the partial key should have been back-filled at least once in six renders"
        )
        expect(rows.all { it.droppedLanes.isEmpty() }, "no lane should have been dropped")

        // An Int lane came back as an Int, and the setter that consumes it did not throw.
        val storedVisible = rows.map { m ->
            m to (rig.scope.loadKey(out.resolve("renders/${m.id}/key.json"))["grid.visible"])
        }
        storedVisible.forEach { (m, visible) ->
            expect(visible is Int, "${m.id}: grid.visible is ${visible?.javaClass?.simpleName}, not Int")
        }

        // An extrapolated key can hold an `Int` lane *outside* the target's declared range — 14
        // spheres out of a possible 9 — and that is deliberate on both sides. The sweep rounds to the
        // anchor's type without clamping, because the blend is the arithmetic it claims to be; the
        // clamp lives in `intTarget`, on apply. Which means the key still reproduces the render
        // exactly, and the archive still records the point in the space that was actually visited.
        val outside = storedVisible.firstOrNull { (_, v) -> v is Int && v !in 1..(GRID * GRID) }
        if (outside == null) {
            println("note: no render extrapolated grid.visible out of range this time")
        } else {
            val (m, stored) = outside
            rig.scope.loadKey(out.resolve("renders/${m.id}/key.json"))()
            pump(renderer, window, 2)
            // Read back as a number, not as an `Int`: `intTarget` registers a *float* lane — which is
            // what gives an integer control meaningful interpolation — so `capture()` answers 9.0
            // where the pool's hand-written keys hold 9. Both apply; only the spelling differs.
            val applied = (rig.scope.capture()["grid.visible"] as? Number)?.toInt()
            println("render ${m.id} stored grid.visible=$stored; the target clamped it to $applied on apply")
            expect(
                applied == GRID * GRID,
                "an out-of-range Int lane must clamp to the target's range on apply, not arrive as $applied"
            )
        }

        // ---- the claim that needs the GPU: the picture is a function of the blend ----
        //
        // Not "consecutive renders differ": consecutive renders are independent draws and can
        // legitimately land next to each other in the space — the run that first exercised this had
        // a 0.74/0.26 blend followed by a 0.67/0.30 one, whose pictures *should* be nearly the same,
        // and asserting otherwise failed the sweeper for being correct. What is actually claimed is
        // that pixel distance tracks key distance, which a blend reaching no uniform at all cannot
        // fake: every picture would then be identical and the correlation undefined.
        val stills = rows.map { readLuma(out.resolve("renders/${it.id}/still.png").toFile()) }
        val keys = rows.map { rig.scope.loadKey(out.resolve("renders/${it.id}/key.json")) }
        expect(stills.all { it.isNotEmpty() }, "a still read back as no pixels")
        expect(
            stills.all { luma -> luma.distinct().size > 8 },
            "a still is nearly uniform — the scene did not render"
        )

        val lanes = keys.first().values.keys.filter { lane -> keys.all { it[lane] is Number || it[lane] is Vector3f } }
        val pairs = buildList {
            for (i in rows.indices) for (j in i + 1 until rows.size) {
                add(Triple(keyDistance(keys[i], keys[j], lanes), meanAbsoluteDifference(stills[i], stills[j]), i to j))
            }
        }
        val widest = pairs.maxBy { it.second }
        val correlation = pearson(pairs.map { it.first }, pairs.map { it.second })
        println(
            "across ${pairs.size} pairs: widest picture difference ${"%.2f".format(widest.second)} luma " +
                "(renders ${widest.third.first} and ${widest.third.second}), " +
                "key-distance/pixel-distance correlation ${"%.2f".format(correlation)}"
        )
        expect(
            widest.second > DIFFERENT_PICTURE_FLOOR,
            "no two renders in the archive differ by more than ${widest.second} luma; the night explored nothing"
        )
        expect(
            pairs.all { it.second > 0.0 },
            "two renders produced pixel-identical stills from different keys"
        )
        expect(
            correlation > 0.6,
            "pixel distance does not track key distance (r = $correlation); the blend is not what is being drawn"
        )

        // ---- and the other half: a key is a complete description of a look ----
        val firstKey = rig.scope.loadKey(out.resolve("renders/${rows[0].id}/key.json"))
        firstKey()
        pump(renderer, window, SETTLE_FRAMES * 3)
        val replayed = readbackLuma(renderer, rig)
        val drift = meanAbsoluteDifference(stills[0], replayed)
        println("re-applying render ${rows[0].id}'s key reproduced its still to $drift luma")
        expect(
            drift < SAME_PICTURE_CEILING,
            "re-applying a saved key gave a different picture ($drift luma); a key is not complete"
        )

        println(sweepArchiveSummary(out))
    }

    private fun pump(renderer: Renderer, window: Window, frames: Int) {
        repeat(frames) {
            window.pollEvents()
            renderer.render()
        }
    }